UnderAutomation
Any question?

[email protected]

Contact us
UnderAutomation
⌘Q

Program: list, start, stop and read the execution

List, select, start, pause, hold and stop robot programs, read their execution and call stack, and read and write program positions with robot.Program. Brand support table, C# and Python examples.

  • Prerequisites
  • Brand support
  • Example
  • List, select and start a program
  • Start from a line, set the cycle mode, hold a program
  • Read the execution state
  • Read and write the positions of a program
  • Reference
  • Methods of IProgramService
  • Methods of IProgramPositionService
  • Result types
  • Errors
  • What to read next

robot.Program lists, selects, starts, pauses and stops the programs of a robot controller, reads their execution state, and reads and writes the positions stored in a program. The same calls work on Fanuc, Yaskawa, Universal Robots, ABB and Stäubli controllers, for the methods that the brand supports.

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 Start and StartAtLine: the controller can need its automatic or remote mode, and the servo power. See State.
  • A program is named with its native name, as the controller names it.

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. The rows Program.Position.* are the methods of robot.Program.Position.

Programs
MethodFanucYaskawaUniversal RobotsABBStäubli
Program.ListCGTP (Cgtp), FTPHigh Speed Ethernet Server, Ethernet Server, FTPSFTPRobot Web ServicesSOAP, Files
Program.SelectCGTP (Cgtp)High Speed Ethernet Server, Ethernet ServerDashboard Server, REST APIRobot Web ServicesSOAP
Program.StartCGTP (Cgtp), CGTP (CgtpKcl), TelnetHigh Speed Ethernet Server, Ethernet ServerDashboard Server, REST APIRobot Web ServicesSOAP
Program.PauseCGTP (Cgtp), CGTP (CgtpKcl), TelnetHigh Speed Ethernet Server, Ethernet ServerDashboard Server, REST APIRobot Web ServicesSOAP
Program.ResumeCGTP (CgtpKcl), TelnetHigh Speed Ethernet Server, Ethernet ServerDashboard Server, REST APIRobot Web ServicesSOAP
Program.StopCGTP (Cgtp), CGTP (CgtpKcl), TelnetNot availableDashboard Server, REST APIRobot Web ServicesSOAP
Program.ReadExecutionSNPX, CGTP (CgtpKcl), Telnet, FTPHigh Speed Ethernet Server, Ethernet ServerDashboard Server, REST APIRobot Web ServicesSOAP
Program.HoldCGTP (CgtpKcl), TelnetHigh Speed Ethernet Server, Ethernet ServerNot availableNot availableNot available
Program.SetCycleModeNot availableHigh Speed Ethernet Server, Ethernet ServerNot availableRobot Web ServicesNot available
Program.SelectAtLineCGTP (Cgtp)High Speed Ethernet Server, Ethernet ServerNot availableRobot Web ServicesNot available
Program.StartAtLineCGTP (Cgtp)High Speed Ethernet Server, Ethernet ServerNot availableRobot Web ServicesNot available
Program.StopTaskCGTP (Cgtp), CGTP (CgtpKcl), TelnetNot availableNot availableNot availableSOAP
Program.Position.ReadFTP, CGTP (Cgtp)FTP, High Speed Ethernet ServerNot availableRobot Web ServicesNot available
Program.Position.WriteCGTP (Cgtp)Not availableNot availableRobot Web ServicesNot available
Program.Position.SetToCurrentCGTP (Cgtp)Not availableNot availableRobot Web ServicesNot available
Program14 of 1511 of 157 of 1513 of 158 of 15

A brand that has no route for a method throws FeatureNotSupportedException (see Errors). Ask robot.Program.IsAvailable(ProgramFeature.StartAtLine) before the call.

Example

List, select and start a program

Select selects a program, so that Start without a name starts it. In Python, an empty name (start("")) starts the selected program. Start("MAIN") starts a program by its name. Pause keeps the program at its line and Resume continues it. Stop aborts the running program.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
foreach (RobotProgramInfo program in robot.Program.List())
Console.WriteLine($"{program.Name} {program.Comment}");
robot.Disconnect();
}
Click to see the full code
RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Native name of the program, as the pendant shows it
robot.Program.Select("MAIN");
robot.Program.Start();
// Pause keeps the program at its line, Resume continues it
robot.Program.Pause();
robot.Program.Resume();
robot.Program.Stop();
robot.Disconnect();
}
Click to see the full code

Start from a line, set the cycle mode, hold a program

StartAtLine starts a program from a line, counted from 1. SetCycleMode sets how far a program runs after a start: one step, one cycle or continuously. Hold decelerates the robot and stops it on its path. On a brand where a hold and a pause are the same function of the controller, both methods send it. StopTask aborts one task and leaves the others running.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Not supported by every brand: ask first
if (robot.Program.IsAvailable(ProgramFeature.StartAtLine))
{
robot.Program.StartAtLine("MAIN", 10);
}
robot.Program.SetCycleMode(CycleMode.OneCycle);
robot.Program.Hold();
robot.Program.StopTask("MAIN");
robot.Disconnect();
}
Click to see the full code

Read the execution state

ReadExecution returns one ProgramExecution per task. Stack is the call stack, the current program first. It is empty when the route does not read it.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
foreach (ProgramExecution execution in robot.Program.ReadExecution())
{
Console.WriteLine($"{execution.Task}: {execution.Program}, line {execution.Line}, {execution.Status}");
foreach (ProgramFrame frame in execution.Stack)
Console.WriteLine($" called from {frame.Program}, line {frame.Line}");
}
robot.Disconnect();
}
Click to see the full code

Read and write the positions of a program

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
foreach (ProgramPosition position in robot.Program.Position.Read("MAIN"))
Console.WriteLine($"{position.Name}: X {position.Position.Pose.X}, Y {position.Position.Pose.Y}, Z {position.Position.Pose.Z}");
robot.Disconnect();
}
Click to see the full code

SetToCurrent writes the current position of the robot in a position of the program and returns it. Write writes a position that you computed. A stored Cartesian position does not depend on the state of the robot at the time of the write: a brand that stores the frame, the tool and the configuration refuses a Cartesian value that does not give them.

RobotController robot = new RobotController();
robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));
// Teach a position at the current place of the robot
RobotPosition taught = robot.Program.Position.SetToCurrent("MAIN", "P[1]");
// Or write a position that you computed
RobotPosition target = robot.Motion.ReadPose();
target.Pose.Z += 50;
robot.Program.Position.Write("MAIN", "P[2]", target);
robot.Disconnect();
}
Click to see the full code

Reference

In Python, the names are in snake_case: robot.program.list(), robot.program.start_at_line(...), robot.program.read_execution(), robot.program.position.read(...). The enum members keep their names.

Methods of IProgramService

Interface
IProgramService
C#Python

Program service of a robot controller: list, select, start, pause, resume and stop programs, and read their execution state. Program files are read and written with the file service. 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
Position
Property
read only
IProgramPositionService
Positions stored in the programs
Hold()
Method
void
Holds the running programs: the robot decelerates and stops on its path, the program stays at its line, Resume continues it. On a brand where the hold and the pause are the same function of the controller, both methods send it. A refusal that the controller answers throws ControllerRefusedException. Some routes get no answer from the controller (the route list of the brand says which): there a refusal is not seen, read ReadExecution to check the result.
IsAvailable(ProgramFeature)
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
List()
Method
RobotProgramInfo[]
Lists the programs of the controller
Pause()
Method
void
Pauses the running program. Resume continues it. On a brand where a hold is another function of the controller, Hold sends it.
ReadExecution()
Method
ProgramExecution[]
Reads the execution state of each task of the controller: program, line, status and call stack (Stack, empty when the route does not read it)
Resume()
Method
void
Resumes the program paused by Pause or Hold. A program stopped on a breakpoint or in step mode continues with Continue.
Select(string)
Method
void
Selects a program, so that Start(string) without name starts it
  • name : Native name of the program
SelectAtLine(string, int)
Method
void
Selects a program with its cursor at a line, so that Start(string) without name starts it from this line
  • name : Native name of the program
  • line : Line of the program, from 1
SetCycleMode(CycleMode)
Method
void
Sets the cycle mode of the controller: step, one cycle or continuous. The mode applies to the next start or resume, for every program. A brand can refuse a mode that its controller does not have with an ArgumentException. For a debug session, use SetStepMode(bool) and Continue: they also work on the brands where the step mode is not a cycle mode.
  • mode : New cycle mode. Unknown is refused.
Start(string)
Method
void
Starts a program. The controller can need its automatic or remote mode and the servo power.
  • name : Native name of the program. Empty (default): the selected program.
StartAtLine(string, int)
Method
void
Starts a program from a line. The controller can need its automatic or remote mode and the servo power. A brand that selects the program first, then starts it, leaves the program selected at this line when the start is refused.
  • name : Native name of the program. Empty: the selected program, on a brand that can read it; the other brands throw ArgumentException.
  • line : Line of the program, from 1
Stop()
Method
void
Stops (aborts) the running program
StopTask(string)
Method
void
Stops (aborts) one task. The other tasks keep running.
  • task : Native name of the task. On a brand whose tasks are named by their program, the name of the root program of the task.

Hold can get no answer from the controller on some routes. A refusal is then not seen: read ReadExecution to check the result.

Methods of IProgramPositionService

Interface
IProgramPositionService
C#Python

Program position service of a robot controller: positions stored in a program, read, written and taught. 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
IsAvailable(ProgramPositionFeature)
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
Read(string)
Method
ProgramPosition[]
Reads the positions stored in a program
  • program : Native name of the program
SetToCurrent(string, string)
Method
RobotPosition
Writes the current position of the robot in a position stored in a program, and returns the position written
  • program : Native name of the program
  • name : Native name of the position in the program, as given by Name
Write(string, string, RobotPosition)
Method
void
Writes a position stored in a program, for the motion group of the value (Group). A joint value writes its joints, a Cartesian value writes its pose with the external axes of the pose (ExternalAxes). A stored Cartesian position does not depend on the state of the robot at the time of the write: a brand whose stored positions keep the number of the frame, the number of the tool and the configuration refuses a Cartesian value with a frame or a tool of -1, or with a posture Same and no configuration object of the brand.
  • program : Native name of the program
  • name : Native name of the position in the program, as given by Name
  • position : New value of the position

Result types

Class
RobotProgramInfo
C#Python

Program of a controller, as listed by the program service. 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
RobotProgramInfo()
Constructor
Creates a program description with the default value of each property
Comment
Property
string
Comment of the program. Empty when the program has none.
Name
Property
string
Name of the program, as used by the other methods of the program service
Native
Property
object
Object of the brand SDK this program comes from. Null when there is none.
Task
Property
string
Task that holds the program, on controllers that load programs per task. Empty otherwise.
ToString()
Method
string
Class
ProgramExecution
C#Python

Execution state of one task of the controller: program, line and status. 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
ProgramExecution()
Constructor
Creates an execution state with the default value of each property
Line
Property
int
Line executed in the program, from 1. 0 when the controller does not give it.
Native
Property
object
Object of the brand SDK this state comes from. Null when there is none.
Program
Property
string
Name of the program executed by the task. Empty when no program is selected.
Stack
Property
ProgramFrame[]
Call stack of the task, current frame first: the first frame is the program and the line executed, the next frames are the calling programs, up to the program the task started with. Empty when the route does not read the call stack. Never null.
Status
Property
ExecutionStatus
Execution status
Task
Property
string
Name of the task. Empty when the controller has only one task without name.
ToString()
Method
string
Enum
ExecutionStatus
C#Python

Execution status of a program

NameValueDescription
Paused
2
The program is paused (held). It can be resumed.
Running
1
The program is running
Stopped
3
No program is running
Unknown
0
The controller does not give the status
Class
ProgramFrame
C#Python

One frame of the call stack of a task: a program and the line executed in it. See Stack. 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
ProgramFrame()
Constructor
Creates a frame of a call stack with the default value of each property
Line
Property
int
Line executed in the program, from 1. 0 when the controller does not give it, for example for a calling program on some controllers.
Program
Property
string
Name of the program of this frame, written like Program
ToString()
Method
string
Class
ProgramPosition
C#Python

Position stored in a program, with its native name and its comment. 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
ProgramPosition()
Constructor
Creates a program position with the default value of each property
Comment
Property
string
Comment of the position. Empty when it has none.
Name
Property
string
Native name of the position in the program, as the program writes it. It is the name given to the other methods of the program position service.
Native
Property
object
Object of the brand SDK this position comes from. Null when there is none.
Position
Property
RobotPosition
The position. Setting null gives a position at the origin.
ToString()
Method
string
Enum
CycleMode
C#Python

Cycle mode of the controller: how far a program runs after a start, for SetCycleMode(CycleMode)

NameValueDescription
Continuous
3
The program runs again from its start each time it reaches its end
OneCycle
2
The program runs once to its end, then stops
Step
1
The program stops after each instruction. The next start or resume runs the next instruction.
Unknown
0
The controller does not give the mode. Refused by SetCycleMode(CycleMode).

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 protocol did not answer at the connection.
  • ControllerRefusedException: the controller received the command and refused it.
  • RobotControllerException: the route failed. Its inner exception is the exception of the brand SDK.
  • ArgumentException: an invalid argument, for example a cycle mode that the controller does not have.

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

What to read next

  • Start, stop and select a robot program: the same start on each brand, with the program names and the modes of each brand.
  • Debug: breakpoints and step mode.
  • State: operating mode and servo power.
  • Alarm: read and reset the alarms that stop a program.