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.
- Prerequisites
- Safety
- Brand support
- Example
- Read the position
- Compute the kinematics
- Read the frames and the tools
- Read the kinematic model
- Move to a joint position
- Move to a Cartesian position
- Move along a line
- Stop the motion
- Reference
- Methods of IMotionService
- RobotPosition
- PositionConfiguration
- MotionSpeed
- KinematicModel
- Errors
- What to read next
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.
| Method | Fanuc | Yaskawa | Universal Robots | ABB | Stäubli |
|---|---|---|---|---|---|
| Motion.ReadPose | SNPX, CGTP (Cgtp), RMI (manual), FTP | High Speed Ethernet Server, Ethernet Server | RTDE, Primary Interface (Primary) | Robot Web Services | SOAP |
| Motion.ReadJoints | SNPX, CGTP (Cgtp), RMI (manual), FTP | Not available | RTDE, Primary Interface (Primary) | Robot Web Services | SOAP |
| Motion.ForwardKinematics | CGTP (Cgtp) | Not available | Primary Interface (Primary) | Robot Web Services | SOAP |
| Motion.InverseKinematics | CGTP (Cgtp) | Not available | Primary Interface (Primary) | Robot Web Services | SOAP |
| Motion.ReadUserFrame | RMI (manual) | Not available | Not available | Not available | Not available |
| Motion.ReadTool | RMI (manual) | Not available | Not available | Not available | Not available |
| Motion.MoveJoint | RMI (manual) | Not available | Primary Interface (Script), Interpreter Mode (manual) | Robot Web Services | SOAP |
| Motion.MoveJointToPose | RMI (manual) | High Speed Ethernet Server, Ethernet Server | Primary Interface (Script), Interpreter Mode (manual) | Robot Web Services | SOAP |
| Motion.MoveLinear | RMI (manual) | High Speed Ethernet Server, Ethernet Server | Primary Interface (Script), Interpreter Mode (manual) | Robot Web Services | SOAP |
| Motion.MoveLinearToJoints | RMI (manual) | Not available | Primary Interface (Script), Interpreter Mode (manual) | Robot Web Services | SOAP |
| Motion.StopMotion | RMI (manual) | High Speed Ethernet Server, Ethernet Server | Primary Interface (Script), Dashboard Server | Robot Web Services | SOAP |
| Motion.WaitForMotionEnd | RMI (manual) | High Speed Ethernet Server, Ethernet Server | Dashboard Server, Primary Interface (Primary) | Robot Web Services | Not available |
| Motion.ForwardKinematicsInFrame | CGTP (Cgtp) | Not available | Not available | Not available | Not available |
| Motion.ReadKinematicModel | FTP | High Speed Ethernet Server | Not available | Not available | Not available |
| Motion | 14 of 14 | 6 of 14 | 10 of 14 | 10 of 14 | 9 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 defaultRobotPosition 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();}
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 positionRobotPosition 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 valuesJointValues joints = robot.Motion.InverseKinematics(position);Console.WriteLine(string.Join(", ", joints.Values));robot.Disconnect();}
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 1CartesianPose 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 toolRobotPosition position = robot.Motion.ForwardKinematicsInFrame(robot.Motion.ReadJoints(), frame: 1, tool: 1);robot.Disconnect();}
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 methodif (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();}
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 axesMotionSpeed speed = new MotionSpeed { Percent = 20 };robot.Motion.MoveJoint(new JointValues(0, 0, 0, 0, -90, 0), speed);robot.Motion.WaitForMotionEnd(30000);robot.Disconnect();}
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 targetrobot.Motion.MoveJointToPose(target, new MotionSpeed { Percent = 20 });robot.Motion.WaitForMotionEnd(30000);robot.Disconnect();}
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/sMotionSpeed speed = new MotionSpeed { Linear = 100 };robot.Motion.MoveLinear(target, speed);robot.Motion.WaitForMotionEnd(30000);// Same move to joint valuesrobot.Motion.MoveLinearToJoints(new JointValues(0, 0, 0, 0, -90, 0), speed);robot.Disconnect();}
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();}
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
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.
| Member | Type | Description |
|---|---|---|
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.
|
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.
|
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.
|
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.
|
MoveJoint(JointValues, MotionSpeed, int) Method | void | Moves to a joint position with a joint interpolation
|
MoveJointToPose(RobotPosition, MotionSpeed) Method | void | Moves to a Cartesian position with a joint interpolation. The configuration of the position chooses the joint solution.
|
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.
|
MoveLinearToJoints(JointValues, MotionSpeed, int) Method | void | Moves to a joint position along a line of the tool center point
|
ReadJoints(int) Method | JointValues | Reads the current joint position of a motion group, in degrees (mm for linear axes)
|
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.
|
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
|
ReadTool(int, int) Method | CartesianPose | Reads a tool: pose of the tool center point in the flange frame
|
ReadUserFrame(int, int) Method | CartesianPose | Reads a user frame, expressed in the world frame of the motion group
|
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.
|
In .NET, a null speed gives the default speed: 10 % for a joint interpolation and 100 mm/s for a linear interpolation.
RobotPosition
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.
| Member | Type | Description |
|---|---|---|
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.
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.
| Member | Type | Description |
|---|---|---|
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. |
Shoulder posture of an arm: position of the wrist center relative to axis 1
| Name | Value | Description |
|---|---|---|
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. |
Elbow posture of an arm: position of the elbow relative to the line from axis 2 to the wrist center
| Name | Value | Description |
|---|---|---|
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 |
Wrist posture of an arm: one of the two wrist solutions, with axis 5 of opposite signs
| Name | Value | Description |
|---|---|---|
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
Speed of a move. The joint interpolation uses Percent, the linear interpolation uses Linear. The speed override of the controller applies on top.
| Member | Type | Description |
|---|---|---|
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
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.
| Member | Type | Description |
|---|---|---|
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 |
Geometry of a 6-axis robot arm, as the kinematics of the brand SDK classifies it from the Denavit-Hartenberg values
| Name | Value | Description |
|---|---|---|
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.WaitForMotionEndthrows it with an innerTimeoutExceptionwhen 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.