UnderAutomation
질문이요?

[email protected]

문의하기
UnderAutomation
⌘Q
이 페이지는 영어로만 제공됩니다.

Motion: read the position and move the robot

Read the position, the kinematics, the frames and the kinematic model of a robot and move it to a joint or Cartesian target with robot.Motion. Safety, brand support table, C# and Python examples.

robot.Motion reads the position of a robot, computes its kinematics, reads the frames, the tools and the kinematic model, and moves the robot to a joint or Cartesian target. The result types are the same on every brand. The methods that you can call depend on the brand: see the table below. The units are mm and degrees. The motion groups are numbered from 1, and the group 1 is the default.

Prerequisites

  • A connected RobotController. See Connect to your robot.
  • The license of the brand of the controller, or the 30 day trial. See Licensing.
  • For the moves: the servo power, see State, and a controller that accepts remote motion. A controller can need its automatic or remote mode.
  • For the moves: a route that is enabled. For example on Fanuc, the only route of the moves takes the motion control of the controller. The library never opens such a route by itself: it is marked (manual) in the table below, and you enable it in the connection parameters of the brand. Until then, the call throws RouteUnavailableException, and its message says what to enable. See Routing.

Safety

The moves move the robot. A robot is dangerous machinery. Test your code on a simulator or an emulator first, then on the real robot with low speeds and a person at the emergency stop. The safety of the controller applies as for any remote command. StopMotion does not replace the emergency stop. The SDK does not replace a safety system: see the Legal notice.

Brand support

Each cell gives the protocol that the method uses on this brand, in the default order. The page Routing explains how the library chooses it. The table is generated from the route data of the library. (manual) marks a route that you enable yourself. "n of m" is the number of methods of the service that have a route on this brand.

Motion
MethodFanucYaskawaUniversal RobotsABBStäubli
Motion.ReadPoseSNPX, CGTP (Cgtp), RMI (manual), FTPHigh Speed Ethernet Server, Ethernet ServerRTDE, Primary Interface (Primary)Robot Web ServicesSOAP
Motion.ReadJointsSNPX, CGTP (Cgtp), RMI (manual), FTPNot availableRTDE, Primary Interface (Primary)Robot Web ServicesSOAP
Motion.ForwardKinematicsCGTP (Cgtp)Not availablePrimary Interface (Primary)Robot Web ServicesSOAP
Motion.InverseKinematicsCGTP (Cgtp)Not availablePrimary Interface (Primary)Robot Web ServicesSOAP
Motion.ReadUserFrameRMI (manual)Not availableNot availableNot availableNot available
Motion.ReadToolRMI (manual)Not availableNot availableNot availableNot available
Motion.MoveJointRMI (manual)Not availablePrimary Interface (Script), Interpreter Mode (manual)Robot Web ServicesSOAP
Motion.MoveJointToPoseRMI (manual)High Speed Ethernet Server, Ethernet ServerPrimary Interface (Script), Interpreter Mode (manual)Robot Web ServicesSOAP
Motion.MoveLinearRMI (manual)High Speed Ethernet Server, Ethernet ServerPrimary Interface (Script), Interpreter Mode (manual)Robot Web ServicesSOAP
Motion.MoveLinearToJointsRMI (manual)Not availablePrimary Interface (Script), Interpreter Mode (manual)Robot Web ServicesSOAP
Motion.StopMotionRMI (manual)High Speed Ethernet Server, Ethernet ServerPrimary Interface (Script), Dashboard ServerRobot Web ServicesSOAP
Motion.WaitForMotionEndRMI (manual)High Speed Ethernet Server, Ethernet ServerDashboard Server, Primary Interface (Primary)Robot Web ServicesNot available
Motion.ForwardKinematicsInFrameCGTP (Cgtp)Not availableNot availableNot availableNot available
Motion.ReadKinematicModelFTPHigh Speed Ethernet ServerNot availableNot availableNot available
Motion14 of 146 of 1410 of 1410 of 149 of 14

A brand that has no route for a method throws FeatureNotSupportedException (see Errors). Ask robot.Motion.IsAvailable(MotionFeature.MoveLinear) before the call. IsAvailable is false for a method whose routes are all disabled or did not answer.

Example

Read the position

ReadPose returns a RobotPosition: the Cartesian pose of the tool center point with its configuration, frame, tool and group, and the joints when the controller gives them. ReadJoints returns the joint position. A position that you read can be given back as a target as it is.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Group 1 by default
RobotPosition pose = robot.Motion.ReadPose();
Console.WriteLine($"X {pose.Pose.X}, Y {pose.Pose.Y}, Z {pose.Pose.Z}");
JointValues joints = robot.Motion.ReadJoints();
Console.WriteLine(string.Join(", ", joints.Values));
robot.Disconnect();
}
Click to see the full code

Compute the kinematics

ForwardKinematics computes the Cartesian position of a joint position, and InverseKinematics the joint position of a Cartesian position, with the configuration, frame, tool and group of the position. The frame and the tool of the forward computation depend on the brand: Frame and Tool of the result give them, and -1 means the ones active on the controller.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Joint values to a position
RobotPosition position = robot.Motion.ForwardKinematics(new JointValues(0, 0, 0, 0, -90, 0));
Console.WriteLine($"X {position.Pose.X}, Y {position.Pose.Y}, Z {position.Pose.Z}");
// Position to joint values
JointValues joints = robot.Motion.InverseKinematics(position);
Console.WriteLine(string.Join(", ", joints.Values));
robot.Disconnect();
}
Click to see the full code

Read the frames and the tools

ReadUserFrame reads a user frame, expressed in the world frame of the motion group. ReadTool reads the pose of the tool center point in the flange frame. ForwardKinematicsInFrame computes a position in a frame and with a tool that you choose. For -1, it uses the frame and the tool active on the controller.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// User frame 1 and tool 1
CartesianPose frame = robot.Motion.ReadUserFrame(1);
CartesianPose tool = robot.Motion.ReadTool(1);
Console.WriteLine($"Frame 1: X {frame.X}, Y {frame.Y}, Z {frame.Z}");
Console.WriteLine($"Tool 1: X {tool.X}, Y {tool.Y}, Z {tool.Z}");
// Position of a joint set seen from a frame and a tool
RobotPosition position = robot.Motion.ForwardKinematicsInFrame(robot.Motion.ReadJoints(), frame: 1, tool: 1);
robot.Disconnect();
}
Click to see the full code

Read the kinematic model

ReadKinematicModel reads the Denavit-Hartenberg values, the geometry and the model name of the arm of a motion group. It is read only. The values follow the convention of the brand: compare models of the same Convention only. A route can read some groups only: another group throws ArgumentOutOfRangeException. A group that is not a robot arm, or a model that the brand cannot read, throws RobotControllerException.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Fanuc and Yaskawa only: the other brands have no route for this method
if (robot.Motion.IsAvailable(MotionFeature.ReadKinematicModel))
{
KinematicModel model = robot.Motion.ReadKinematicModel();
Console.WriteLine($"{model.Model}: {model.Category}, A1 {model.A1}, A2 {model.A2}, A3 {model.A3}, D4 {model.D4}");
}
robot.Disconnect();
}
Click to see the full code

Move to a joint position

MoveJoint moves to a joint position with a joint interpolation. The speed is a MotionSpeed: for a joint interpolation, Percent is the percentage of the maximum speed of the axes. The controller speed override applies on top. A move returns when the controller accepted the motion, without waiting for its end: WaitForMotionEnd waits for it.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Joint interpolation: 20 % of the maximum speed of the axes
MotionSpeed speed = new MotionSpeed { Percent = 20 };
robot.Motion.MoveJoint(new JointValues(0, 0, 0, 0, -90, 0), speed);
robot.Motion.WaitForMotionEnd(30000);
robot.Disconnect();
}
Click to see the full code

Move to a Cartesian position

MoveJointToPose moves to a Cartesian position with a joint interpolation. The configuration of the position chooses the joint solution. The example reads the current position, raises it by 50 mm and moves there.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
RobotPosition target = robot.Motion.ReadPose();
target.Pose.Z += 50;
// Joint interpolation to a Cartesian target
robot.Motion.MoveJointToPose(target, new MotionSpeed { Percent = 20 });
robot.Motion.WaitForMotionEnd(30000);
robot.Disconnect();
}
Click to see the full code

Move along a line

MoveLinear moves the tool center point along a line to a Cartesian position, and MoveLinearToJoints does it to a joint position. The configuration cannot change along a line. For a linear interpolation, Linear of the MotionSpeed is the speed of the tool center point in mm/s.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
RobotPosition target = robot.Motion.ReadPose();
target.Pose.Z += 50;
// Linear interpolation: tool center point at 100 mm/s
MotionSpeed speed = new MotionSpeed { Linear = 100 };
robot.Motion.MoveLinear(target, speed);
robot.Motion.WaitForMotionEnd(30000);
// Same move to joint values
robot.Motion.MoveLinearToJoints(new JointValues(0, 0, 0, 0, -90, 0), speed);
robot.Disconnect();
}
Click to see the full code

Stop the motion

StopMotion stops a motion that was started by the moves of this service.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
robot.Motion.StopMotion();
robot.Disconnect();
}
Click to see the full code

Reference

In Python, the names are in snake_case: robot.motion.read_pose(), robot.motion.move_linear(target, speed), robot.motion.wait_for_motion_end(30000), robot.motion.is_available(...). The enum members keep their names.

Methods of IMotionService

Interface
IMotionService
C#Python

Motion service of a robot controller: current position, kinematics, frames and tools, and point-to-point moves. Units: mm and degrees. Motion groups are numbered from 1. The moves return when the controller accepted the motion, without waiting for its end: WaitForMotionEnd(int%Int32) waits for it. They need the servo power. The safety of the controller applies as for any remote command. StopMotion does not replace the emergency stop. The library implements this interface. A minor version of the library can add members to it: a class of the application that implements it, for example a test double, then needs the new methods. Errors of the methods other than IsAvailable: FeatureNotSupportedException when the brand has no route for the method, RouteUnavailableException when the method has routes but none of them can be used, ControllerRefusedException when the controller received the command and refused it, RobotControllerException when the route failed (the inner exception is the exception of the brand SDK), and ArgumentException or a derived exception for an invalid argument. IsAvailable only throws ArgumentOutOfRangeException, for a value that is not in the enum. Results: a text and an array are empty when there is no value, never null. The only null values are the Native properties when there is no object of the brand SDK, and Position when the variable is not a position.

MemberTypeDescription
ForwardKinematics(JointValues, int)
Method
RobotPosition
Computes the Cartesian position of a joint position. The frame and the tool of the computation depend on the brand: Frame and Tool of the result give them (-1: the ones active on the controller). ForwardKinematicsInFrame(JointValues%Int32%Int32%Int32) chooses them.
  • joints : Joint position, in degrees (mm for linear axes)
  • group : Motion group, from 1 (default 1)
ForwardKinematicsInFrame(JointValues, int, int, int)
Method
RobotPosition
Computes the Cartesian position of a joint position in a user frame and with a tool. Frame and Tool of the result give the numbers of the frame and of the tool of the computation. For -1, they are the numbers of the frame and of the tool active on the controller at the time of the call, or -1 when the controller does not give them.
  • joints : Joint position, in degrees (mm for linear axes)
  • frame : Number of the user frame. -1: the frame active on the controller.
  • tool : Number of the tool. -1: the tool active on the controller.
  • group : Motion group, from 1 (default 1)
InverseKinematics(RobotPosition)
Method
JointValues
Computes the joint position of a Cartesian position, with the configuration, frame, tool and group of the position. A frame or a tool of -1 is the one active on the controller.
  • position : Cartesian position
IsAvailable(MotionFeature)
Method
bool
Returns true when the method can be called on the connected controller. The answer depends on the brand, on the routing settings and on the protocols that answered at the connection, not on the state of the controller.
  • feature : Method of the service
MoveJoint(JointValues, MotionSpeed, int)
Method
void
Moves to a joint position with a joint interpolation
  • target : Joint position, in degrees (mm for linear axes)
  • speed : Speed. Null: the default speed (Percent).
  • group : Motion group, from 1 (default 1)
MoveJointToPose(RobotPosition, MotionSpeed)
Method
void
Moves to a Cartesian position with a joint interpolation. The configuration of the position chooses the joint solution.
  • target : Cartesian position, with its configuration, frame, tool and group
  • speed : Speed. Null: the default speed (Percent).
MoveLinear(RobotPosition, MotionSpeed)
Method
void
Moves to a Cartesian position along a line of the tool center point. The configuration cannot change along a line.
  • target : Cartesian position, with its frame, tool and group
  • speed : Speed. Null: the default speed (Linear).
MoveLinearToJoints(JointValues, MotionSpeed, int)
Method
void
Moves to a joint position along a line of the tool center point
  • target : Joint position, in degrees (mm for linear axes)
  • speed : Speed. Null: the default speed (Linear).
  • group : Motion group, from 1 (default 1)
ReadJoints(int)
Method
JointValues
Reads the current joint position of a motion group, in degrees (mm for linear axes)
  • group : Motion group, from 1 (default 1)
ReadKinematicModel(int)
Method
KinematicModel
Reads the kinematic model of the robot arm of a motion group: its Denavit-Hartenberg values, its geometry and its model name. Read only. A geometry that the brand does not classify gives Unknown with its values. A route can read some groups only: another group throws ArgumentOutOfRangeException. A group without kinematic values (not a robot arm), or a model that the brand cannot read (no catalog entry, a file that cannot be read), throws RobotControllerException.
  • group : Motion group, from 1 (default 1)
ReadPose(int)
Method
RobotPosition
Reads the current Cartesian position of a motion group, with its configuration, frame and tool, and the joints when the controller gives them
  • group : Motion group, from 1 (default 1)
ReadTool(int, int)
Method
CartesianPose
Reads a tool: pose of the tool center point in the flange frame
  • tool : Number of the tool
  • group : Motion group, from 1 (default 1)
ReadUserFrame(int, int)
Method
CartesianPose
Reads a user frame, expressed in the world frame of the motion group
  • frame : Number of the user frame
  • group : Motion group, from 1 (default 1)
StopMotion()
Method
void
Stops a motion started by the moves of this service
WaitForMotionEnd(int, int)
Method
void
Waits for the end of the motion started by the moves of this service. Throws RobotControllerException with an inner TimeoutException when the motion is not finished after the timeout.
  • timeoutMs : Timeout in milliseconds
  • group : Motion group, from 1 (default 1)

In .NET, a null speed gives the default speed: 10 % for a joint interpolation and 100 mm/s for a linear interpolation.

RobotPosition

Class
RobotPosition
C#Python

Position of a motion group: Cartesian pose of the tool center point in a frame, optional joint values, configuration, frame, tool and group. A position read on the robot can be given back as a target as it is.

MemberTypeDescription
RobotPosition()
Constructor
Creates a position at the origin, with the frame and the tool active on the controller, for group 1
Configuration
Property
PositionConfiguration
Configuration of the arm. Setting null gives a configuration where every posture is Same.
Frame
Property
int
Number of the user frame of the pose. -1 (default): the frame active on the controller.
Group
Property
int
Number of the motion group, from 1 (default 1)
HasJoints
Property
read only
bool
True when Joints has values
Joints
Property
JointValues
Joint values of the same position, when they are known. Empty (no axis) otherwise. Setting null gives an empty joint position.
Native
Property
object
Object of the brand SDK this position comes from. Null when there is none.
Pose
Property
CartesianPose
Cartesian pose of the tool center point in the frame, in mm and degrees. Setting null gives a pose at the origin.
Tool
Property
int
Number of the tool of the pose. -1 (default): the tool active on the controller.
ToString()
Method
string

PositionConfiguration

A target uses, in this order: the configuration object of the brand, the solution closest to NearJoints, then the postures, where Same takes the posture of the current position of the robot.

Class
PositionConfiguration
C#Python

Configuration of a Cartesian position: which joint solution of the arm reaches the pose. A target uses, in this order: the configuration object of the brand (Native), the solution closest to NearJoints, then the postures, where Same takes the posture of the current position of the robot.

MemberTypeDescription
PositionConfiguration()
Constructor
Creates a configuration with the default value of each property
Elbow
Property
ElbowPosture
Elbow posture
HasNearJoints
Property
read only
bool
True when NearJoints has values
Native
Property
object
Configuration object of the brand SDK, turns of the axes included. Filled by every read of a position on the brands that have one. A target with a configuration object of the brand of the controller goes back to the same joints. A configuration object of another brand is ignored.
NearJoints
Property
JointValues
Joint position used to choose the solution: the solution closest to it is taken. Empty (no axis) when not set. A read of a position fills it with the joints of the robot at the time of the read. Setting null gives an empty joint position.
Shoulder
Property
ShoulderPosture
Shoulder posture
Wrist
Property
WristPosture
Wrist posture
ToString()
Method
string
Configuration as the brand writes it when Native is set, otherwise the three postures. For display and logs only.
Enum
ShoulderPosture
C#Python

Shoulder posture of an arm: position of the wrist center relative to axis 1

NameValueDescription
Back
2
The arm reaches behind axis 1, over its own back
Front
1
The wrist center is in front of axis 1
Same
0
In a target: the posture of the current position of the robot. In a read: the controller does not give the posture.
Enum
ElbowPosture
C#Python

Elbow posture of an arm: position of the elbow relative to the line from axis 2 to the wrist center

NameValueDescription
Down
2
The elbow is below the line from axis 2 to the wrist center
Same
0
In a target: the posture of the current position of the robot. In a read: the controller does not give the posture.
Up
1
The elbow is above the line from axis 2 to the wrist center
Enum
WristPosture
C#Python

Wrist posture of an arm: one of the two wrist solutions, with axis 5 of opposite signs

NameValueDescription
Flip
2
Wrist flipped
NoFlip
1
Wrist not flipped
Same
0
In a target: the posture of the current position of the robot. In a read: the controller does not give the posture.

Same in a target is the posture of the current position of the robot. In a read, it means that the controller does not give the posture.

MotionSpeed

Class
MotionSpeed
C#Python

Speed of a move. The joint interpolation uses Percent, the linear interpolation uses Linear. The speed override of the controller applies on top.

MemberTypeDescription
MotionSpeed()
Constructor
Creates a speed with the default value of each property
Linear
Property
double
Linear interpolation: speed of the tool center point in mm/s, greater than 0 (default 100)
Percent
Property
double
Joint interpolation: percentage of the maximum speed of the axes, greater than 0 and up to 100 (default 10)
ToString()
Method
string

Setting Percent or Linear out of range throws ArgumentOutOfRangeException.

KinematicModel

Class
KinematicModel
C#Python

Kinematic model of the robot arm of a motion group: its Denavit-Hartenberg values, its geometry and its model name, read only. The values follow the convention of the brand (signs, offsets, coupling of the axes 2 and 3): compare models of the same Convention only. The model has the values of a 6-axis arm that the kinematics of the brands use: no D1 (height of the base) and no offset of the joints 1, 4 and 6. The library creates a new object at each call and does not read it back. The setters are public so that tests and serializers can build the object.

MemberTypeDescription
KinematicModel()
Constructor
Creates an empty model of group 1, whose category is unknown
A1
Property
double
Link length A1 in mm
A2
Property
double
Link length A2 in mm
A3
Property
double
Link length A3 in mm
Category
Property
KinematicCategory
Geometry of the arm, as the brand SDK classifies it
Convention
Property
string
Name of the convention of the values, given by the brand adapter (the name of the brand in lower case): the Denavit-Hartenberg table of the kinematics of its SDK
D4
Property
double
Link offset D4 in mm
D5
Property
double
Link offset D5 in mm
D6
Property
double
Link offset D6 in mm
Group
Property
int
Number of the motion group, from 1
J2J3Coupling
Property
bool
True when the angle of the joint 3 is measured from the horizontal, so that the forearm turns with the joints 2 and 3 together
Model
Property
string
Name of the robot model, as the controller or the catalog gives it. Empty when it is not known.
Native
Property
object
Object of the brand SDK the values come from. Null when there is none.
Source
Property
string
Where the values come from: "catalog" (the catalog of robot models of the brand SDK) or the name of the file read on the controller
Theta2
Property
double
Offset of the joint 2 in degrees, 0 when the convention of the brand has none
Theta3
Property
double
Offset of the joint 3 in degrees, 0 when the convention of the brand has none
Theta5
Property
double
Offset of the joint 5 in degrees, 0 when the convention of the brand has none
CatalogSource
Field
string
Value of Source for values from the catalog of robot models of the brand SDK
ToString()
Method
string
Enum
KinematicCategory
C#Python

Geometry of a 6-axis robot arm, as the kinematics of the brand SDK classifies it from the Denavit-Hartenberg values

NameValueDescription
InlineJ5OffsetWrist
3
Wrist offset along the axis 5 with no shoulder and no elbow offset (A1 = 0, A3 = 0, D5 not 0), for example some collaborative arms
J5OffsetWrist
2
Ortho-parallel base with a wrist offset along the axis 5: the axes 4 and 6 do not meet
Opw
1
Ortho-parallel base with a spherical wrist: the axes 4, 5 and 6 meet at one point
Unknown
0
The brand SDK does not classify the arm (another geometry, or no classification given)

The model has the values of a 6-axis arm: no height of the base and no offset of the joints 1, 4 and 6.

Errors

The page Errors explains each exception and how to avoid it.

  • FeatureNotSupportedException: the brand has no route for the method.
  • RouteUnavailableException: the method has routes, but none of them can be used, for example because the route is marked (manual) and not enabled, or because the protocol did not answer at the connection.
  • ControllerRefusedException: the controller received the command and refused it, for example a move that the controller does not accept in its current state.
  • RobotControllerException: the route failed. Its inner exception is the exception of the brand SDK. WaitForMotionEnd throws it with an inner TimeoutException when the motion is not finished after the timeout.
  • ArgumentException: an invalid argument.

IsAvailable only throws ArgumentOutOfRangeException, for a value that is not in the enum.

What to read next

  • Get the current position of a robot: the same read on each brand.
  • Move a robot from a PC: the same move on each brand, with what each controller needs before a move.
  • State: switch the servo power on before a move.
  • Routing: enable a route that is off at start.
  • Errors: catch the exceptions of the common API.