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.
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
StartandStartAtLine: 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.
| Method | Fanuc | Yaskawa | Universal Robots | ABB | Stäubli |
|---|---|---|---|---|---|
| Program.List | CGTP (Cgtp), FTP | High Speed Ethernet Server, Ethernet Server, FTP | SFTP | Robot Web Services | SOAP, Files |
| Program.Select | CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Start | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Pause | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Resume | CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Stop | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | Not available | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.ReadExecution | SNPX, CGTP (CgtpKcl), Telnet, FTP | High Speed Ethernet Server, Ethernet Server | Dashboard Server, REST API | Robot Web Services | SOAP |
| Program.Hold | CGTP (CgtpKcl), Telnet | High Speed Ethernet Server, Ethernet Server | Not available | Not available | Not available |
| Program.SetCycleMode | Not available | High Speed Ethernet Server, Ethernet Server | Not available | Robot Web Services | Not available |
| Program.SelectAtLine | CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Not available | Robot Web Services | Not available |
| Program.StartAtLine | CGTP (Cgtp) | High Speed Ethernet Server, Ethernet Server | Not available | Robot Web Services | Not available |
| Program.StopTask | CGTP (Cgtp), CGTP (CgtpKcl), Telnet | Not available | Not available | Not available | SOAP |
| Program.Position.Read | FTP, CGTP (Cgtp) | FTP, High Speed Ethernet Server | Not available | Robot Web Services | Not available |
| Program.Position.Write | CGTP (Cgtp) | Not available | Not available | Robot Web Services | Not available |
| Program.Position.SetToCurrent | CGTP (Cgtp) | Not available | Not available | Robot Web Services | Not available |
| Program | 14 of 15 | 11 of 15 | 7 of 15 | 13 of 15 | 8 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();}
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));// Native name of the program, as the pendant shows itrobot.Program.Select("MAIN");robot.Program.Start();// Pause keeps the program at its line, Resume continues itrobot.Program.Pause();robot.Program.Resume();robot.Program.Stop();robot.Disconnect();}
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 firstif (robot.Program.IsAvailable(ProgramFeature.StartAtLine)){robot.Program.StartAtLine("MAIN", 10);}robot.Program.SetCycleMode(CycleMode.OneCycle);robot.Program.Hold();robot.Program.StopTask("MAIN");robot.Disconnect();}
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();}
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();}
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 robotRobotPosition taught = robot.Program.Position.SetToCurrent("MAIN", "P[1]");// Or write a position that you computedRobotPosition target = robot.Motion.ReadPose();target.Pose.Z += 50;robot.Program.Position.Write("MAIN", "P[2]", target);robot.Disconnect();}
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
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.
| Member | Type | Description |
|---|---|---|
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.
|
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
|
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
|
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.
|
Start(string) Method | void | Starts a program. The controller can need its automatic or remote mode and the servo power.
|
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.
|
Stop() Method | void | Stops (aborts) the running program |
StopTask(string) Method | void | Stops (aborts) one task. The other tasks keep running.
|
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
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.
| Member | Type | Description |
|---|---|---|
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.
|
Read(string) Method | ProgramPosition[] | Reads the positions stored in a 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
|
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.
|
Result types
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.
| Member | Type | Description |
|---|---|---|
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 |
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.
| Member | Type | Description |
|---|---|---|
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 |
Execution status of a program
| Name | Value | Description |
|---|---|---|
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 |
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.
| Member | Type | Description |
|---|---|---|
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 |
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.
| Member | Type | Description |
|---|---|---|
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 |
Cycle mode of the controller: how far a program runs after a start, for SetCycleMode(CycleMode)
| Name | Value | Description |
|---|---|---|
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.