File: list, transfer and delete files
List, download, upload, read, write, delete and rename the files and directories of a robot controller with robot.File. Brand support table, C# and Python examples.
robot.File lists, reads, writes, deletes and renames the files and the directories of a robot controller, and transfers them to and from the PC. The paths use the native syntax of the controller. The result type is the same on every brand. The methods that you can call depend on the brand: see the table below.
Prerequisites
- A connected
RobotController. See Connect to your robot. - The license of the brand of the controller, or the 30 day trial. See Licensing.
- A path in the native syntax of the controller, for example
md:/MAIN.TPon a Fanuc controller.RemoteFileInfo.FullPathgives a path that you can give to the other methods. - Upload, write, delete and rename change the controller. A file that you upload or write replaces the file of the same path.
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 |
|---|---|---|---|---|---|
| File.List | FTP, CGTP (Cgtp) | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.Download | FTP | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.ReadBytes | FTP | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.ReadText | FTP, CGTP (Cgtp) | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.Upload | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.WriteBytes | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.WriteText | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.Delete | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.Exists | FTP | FTP | SFTP | Robot Web Services | Files |
| File.Rename | FTP | Not available | SFTP | Robot Web Services | Files |
| File.CreateDirectory | FTP | Not available | SFTP | Robot Web Services | Files |
| File.DeleteDirectory | FTP | Not available | SFTP | Robot Web Services | Files |
| File.ReadBytesWithProgress | FTP | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.WriteBytesWithProgress | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File | 14 of 14 | 11 of 14 | 14 of 14 | 14 of 14 | 14 of 14 |
A brand that has no route for a method throws FeatureNotSupportedException (see Errors). Ask robot.File.IsAvailable(FileFeature.CreateDirectory) before the call.
Example
List a directory
List returns the files and the directories of a directory. IsDirectory is true for a directory, and Size is 0 for a directory or when the controller does not give it. Check HasModificationDate before you use ModificationDate.
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));// Native syntax of the controller. "md:" is the memory device of a Fanuc controller.foreach (RemoteFileInfo file in robot.File.List("md:/"))Console.WriteLine($"{(file.IsDirectory ? "[dir]" : file.Size + " bytes")} {file.FullPath}");robot.Disconnect();}
Download a file
Download writes a file of the controller to a local file, and replaces it when it exists. ReadBytes keeps the content in memory.
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));robot.File.Download("md:/MAIN.TP", @"C:\Temp\MAIN.TP");// Or keep the content in memorybyte[] content = robot.File.ReadBytes("md:/MAIN.TP");robot.Disconnect();}
Upload a file
Upload writes a local file on the controller, and replaces the file of the controller when it exists. WriteBytes writes the content that you have in memory.
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));// Replaces the file when it existsrobot.File.Upload(@"C:\Temp\MAIN.TP", "md:/MAIN.TP");robot.Disconnect();}
Read and write a text file
WriteText and ReadText handle a file as text. Exists returns true when a file or a directory exists on the controller. Delete deletes a file.
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));robot.File.WriteText("md:/NOTES.TXT", "Cell 3");if (robot.File.Exists("md:/NOTES.TXT")){Console.WriteLine(robot.File.ReadText("md:/NOTES.TXT"));robot.File.Delete("md:/NOTES.TXT");}robot.Disconnect();}
Create, rename and delete directories
CreateDirectory and DeleteDirectory create and delete a directory. Rename renames or moves a file. A brand can have no route for some of these methods: ask IsAvailable first.
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));// Not supported by every brand: ask firstif (robot.File.IsAvailable(FileFeature.CreateDirectory)){robot.File.CreateDirectory("md:/backup");robot.File.Rename("md:/MAIN.TP", "md:/backup/MAIN.TP");robot.File.DeleteDirectory("md:/backup");}robot.Disconnect();}
Follow a transfer
ReadBytesWithProgress and WriteBytesWithProgress do the same as ReadBytes and WriteBytes, with a progress callback and a cancellation. The callback receives the bytes transferred and the size of the file, or -1 when the size is not known yet. It is called on the thread of the transfer. The routes that have a progress call it during the transfer, the other routes only once at the end. The calls never go back, and the last one gives the size twice. A cancelled transfer throws OperationCanceledException. The cancellation is checked before the transfer, and during the transfer by the routes that have a progress: the transfer stops at the next block, and a file that you write can then be incomplete.
These two methods are not in the .NET Framework 3.5 build. The Python package has no wrapper for them: in Python, use read_bytes and write_bytes.
RobotController robot = new RobotController();robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));using CancellationTokenSource cancellation = new CancellationTokenSource();// Bytes received and size of the file, -1 when the size is not known yetbyte[] content = robot.File.ReadBytesWithProgress("md:/MAIN.TP",(done, total) => Console.WriteLine($"{done} / {total}"),cancellation.Token);robot.Disconnect();}
Reference
In Python, the names are in snake_case: robot.file.list("md:/"), robot.file.read_bytes(...), robot.file.create_directory(...), robot.file.is_available(...). The enum members keep their names. read_bytes returns a list of integers.
Methods of IFileService
File service of a robot controller: list, read, write, delete and rename files and directories. Paths use the native syntax of the controller. 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 |
|---|---|---|
CreateDirectory(string) Method | void | Creates a directory on the controller
|
Delete(string) Method | void | Deletes a file of the controller
|
DeleteDirectory(string) Method | void | Deletes a directory of the controller
|
Download(string, string) Method | void | Downloads a file of the controller to a local file
|
Exists(string) Method | bool | Returns true when a file or a directory exists on the controller
|
IsAvailable(FileFeature) 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(string) Method | RemoteFileInfo[] | Lists the files and directories of a directory
|
ReadBytes(string) Method | byte[] | Reads the content of a file of the controller
|
ReadText(string) Method | string | Reads the content of a text file of the controller
|
Rename(string, string) Method | void | Renames or moves a file of the controller
|
Upload(string, string) Method | void | Uploads a local file to the controller
|
WriteBytes(string, byte[]) Method | void | Writes the content of a file of the controller
|
WriteText(string, string) Method | void | Writes the content of a text file of the controller
|
Two methods are not in the .NET Framework 3.5 build, so the table above does not show them, and they have no Python wrapper:
byte[] ReadBytesWithProgress(string remotePath, Action<long, long> progress, CancellationToken cancellationToken): reads the content of a file.progressreceives the bytes received and the size of the file, and can be null.void WriteBytesWithProgress(string remotePath, byte[] data, Action<long, long> progress, CancellationToken cancellationToken): writes the content of a file, replaced when it exists.progressreceives the bytes sent and the size of the data, and can be null.
RemoteFileInfo
File or directory on the controller. 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 |
|---|---|---|
RemoteFileInfo() Constructor | Creates a file description with the default value of each property | |
FullPath Property | string | Full path, in the native syntax of the controller. It can be given to the other methods of the file service. |
HasModificationDate Property | bool | True when the controller gives the date of the last modification |
IsDirectory Property | bool | True for a directory |
ModificationDate Property | DateTime | Date of the last modification, in the time of the controller. Valid only when HasModificationDate is true. |
Name Property | string | Name of the file or directory, without its directory |
Native Property | object | Object of the brand SDK this file comes from. Null when there is none. |
Size Property | long | Size in bytes. 0 for a directory or when the controller does not give it. |
ToString() Method | string |
A text and an array are empty when there is no value, never null. The result is a new object at each call.
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.OperationCanceledException: the transfer ofReadBytesWithProgressorWriteBytesWithProgresswas cancelled.
IsAvailable only throws ArgumentOutOfRangeException, for a value that is not in the enum.
What to read next
- Transfer files to and from a robot controller: the same transfer on each brand, with the paths of each brand.
- Program: list and start the programs that you transferred.
- Alarm: read the alarm history of the controller.
- Errors: catch the exceptions of the common API.