Tcl Scripting

FlatCAM Evo uses the Tcl language for scripting. A script runs the same commands that you type in the Tcl Shell. Use a script to repeat a job, to run many files in a batch, or to run a job without the window (see Command Line and Headless).

What Tcl scripting is for

• Automation: A script opens, processes, and exports the files of a job in one run.
• Repeated jobs: Change one value, for example the tool diameter, and run the same job again.
• Headless batch: Run many jobs from the command line, with no window and no display.

Each Tcl command has a name and arguments. Each argument starts with a dash (-). Example: isolate top -dia 0.2 -outname top_iso.

The full list of commands and arguments is in Tcl Command Reference.

The Tcl Shell

The Tcl Shell is a panel at the bottom of the main window. It runs one command at a time. For more details, see Tcl Shell.

• Type a command and press Enter. The shell shows the result or the error.
• Type help to list all commands.
• Type help <command> to show the arguments of one command. Example: help isolate.
• Use the Up and Down keys to go through the command history.

Screenshot placeholder: images/Tcl-Scripting-1.png - the Tcl Shell panel at the bottom of the main window, with a help isolate command and its output.

Script objects

A script is also a project object of type Script. A Script object holds the Tcl code and runs it. For details, see Script Object.

Open the File menu and go to Scripting. It has these entries:

Entry	What it does
New Script...	Creates an empty Script object and opens it in the code editor.
Open Script...	Opens a Tcl file (.FlatScript, .tcl, or .txt) in the code editor.
Open Example...	Opens an example script from the assets/examples folder.
Run Script...	Runs the opened Tcl script. Shortcut: Shift+S.

The Shell toolbar has buttons for New Script, Open Script, and Run Script.

Run a script in this order:

1. Open or create the script.
2. Click Run Script or press Shift+S.
3. Read the result in the Tcl Shell.

The script runs on the GUI thread. The script must belong to the active project. If the script belongs to another project, the shell shows an error and the script does not run.

Screenshot placeholder: images/Tcl-Scripting-2.png - the File > Scripting menu with the four entries.

Running a script at start and headless

Run a script when FlatCAM Evo starts with the --shellfile option:

flatcam.py --shellfile=D:\PCB\job.FlatScript

Other start options:

Option	What it does
--shellfile=<file>	Runs the Tcl file when the application starts.
--shellvar=<values>	Sets the variables shellvar_0, shellvar_1, and so on. Example: --shellvar=1,'C:\path',23.
--command="<commands>"	Runs Tcl commands. Separate the commands with ;.
--headless	Runs with no window and no OpenGL.

Headless mode runs the options in this order: --shellvar, --shellfile, then --command. Example:

flatcam.py --headless --shellfile=D:\PCB\job.FlatScript --shellvar=D:\PCB\top.gbr

Without --shellfile and --command, headless mode reads the Tcl commands from the standard input.

Exit codes in headless mode:

Code	Meaning
0	The job is done.
1	A Tcl command failed.
2	The command line is not valid.
N	The script ran exit N.

For more details, see Command Line and Headless.

Tcl syntax basics

Only a few Tcl rules are needed for FlatCAM Evo scripts.

Variables and set. Use set to create a variable. Use $ to read its value:

set dia 0.2
isolate top -dia $dia -outname top_iso

Quoting.

• Words are separated by spaces.
• "..." allows variable substitution. Example: "top_$dia".
• {...} stops all substitution. Use braces for long text.
• [...] runs a command and uses its result. Example: set n [llength $list].
• # at the start of a line is a comment.

File paths on Windows. A backslash (\) is an escape character in Tcl. Use one of these ways:

• Forward slashes: D:/PCB/top.gbr.
• Braces: {D:\PCB\top.gbr}.

Use braces when a path has spaces: open_gerber {D:/My Boards/top.gbr}.

Loops.

foreach dia {0.1 0.2 0.3} {
    isolate top -dia $dia -outname top_iso_$dia
}

for {set i 1} {$i <= 3} {incr i} {
    puts "pass $i"
}

puts writes text to the Tcl Shell.

Example: single-sided PCB job

This script makes the isolation G-code, the board cutout G-code, and the drilling G-code of one single-sided board. The file names and values are examples. Change them for your board. Use the commands listed in Tcl Command Reference to check the arguments.

# 1. Open the files
open_gerber {D:/PCB/board/top.gbr} -outname top
open_excellon {D:/PCB/board/drill.drl} -outname drills

# 2. Isolation routing: a Geometry object from the Gerber object
isolate top -dia 0.2 -passes 1 -outname top_iso

# 3. CNC job for the isolation Geometry
cncjob top_iso -z_cut -0.1 -z_move 2 -feedrate 300 -feedrate_rapid 1500 -outname top_iso_cnc
write_gcode top_iso_cnc {D:/PCB/gcode/top_iso.gcode}

# 4. Board cutout: a Geometry object around the board
cutout top -dia 1.5 -margin 0.5 -gapsize 0.6 -gaps tb -outname board_cut

# 5. CNC job for the cutout Geometry
cncjob board_cut -z_cut -1.8 -z_move 2 -feedrate 200 -feedrate_rapid 1500 -outname board_cut_cnc
write_gcode board_cut_cnc {D:/PCB/gcode/cut.gcode}

# 6. Drilling: a CNC job directly from the Excellon object
drillcncjob drills -drillz -1.8 -travelz 2 -feedrate_z 60 -feedrate_rapid 1500 -outname drills_cnc
write_gcode drills_cnc {D:/PCB/gcode/drill.gcode}

Notes on this example:

• isolate and cutout make Geometry objects. cncjob makes a CNC job from a Geometry object.
• drillcncjob makes a CNC job from an Excellon object. You do not need cncjob for it.
• write_gcode saves the G-code of one CNC job to a file. Each job needs its own write_gcode line.
• cncjob takes the preprocessor name with -pp. The name is case sensitive and has no quotes. If you do not set -pp, the application uses its own value. To list the preprocessor names, run list_pp in the Tcl Shell.
• drillcncjob sets the name <name>_cnc when you do not set -outname.

Screenshot placeholder: images/Tcl-Scripting-3.png - the Project panel after the script ran, with the Gerber, Excellon, Geometry, and CNC Job objects.

Async and blocking behavior

Many commands run in the background (they use TclCommandSignaled). Examples: open_gerber, open_excellon, isolate, cncjob, drillcncjob, write_gcode, and plot_all. The script waits until each command finishes. The next command starts after the previous one is done. cutout is not a signaled command, and it has no -timeout argument.

Each signaled command accepts an extra argument, -timeout <milliseconds>:

• -timeout sets the maximum wait time for one command.
• The default value is 300000 milliseconds (5 minutes). This is the application option global_background_timeout.
• The value must be from 1 to 2147483647.

Example: isolate top -dia 0.2 -outname top_iso -timeout 600000 waits up to 10 minutes.

If a command takes longer than the timeout, the shell shows this error: "Operation timed out. Queued or running work has not been cancelled. Consider increasing -timeout ." The work keeps running in the background. The script stops. Changes are not rolled back. A new script run is refused until the timed-out work ends.

Errors

• A failed command shows an error in the Tcl Shell. The shell shows the error text and the error details.
• A failed Script object run stops at the first error. The shell shows the error. The editor moves the cursor to the line of the error.
• Commands that ran before the error keep their changes. The application does not undo them.
• In headless mode, the error is written to the standard error output. The exit code is 1.
• Use help <command> to check the arguments. Most errors are a missing required argument or a wrong name.

Tips and limits

• Tcl commands do not plot. A command that creates an object does not draw it on the canvas. Run plot_all to draw all objects. Use plot_all -plot_status False to hide them.
• Use the same object names in each step. A wrong name gives an error.
• Name each output object with -outname. This makes the next step easy to write.
• Test a new script step by step in the Tcl Shell before you put it in a script.
• Use forward slashes or braces for Windows paths.
• The values in a script are in mm. In a project with inch units, the values are in inch.
• A script that changes objects can change the project. Save the project after a run if you want to keep the changes. See Projects.

See also

• Tcl Shell
• Tcl Command Reference
• Script Object
• Command Line and Headless
• Isolation Routing
• Cutout
• Drilling
• Exporting Files
• Preprocessors
• FAQ and Troubleshooting