NGCGUI

Table of Contents

JavaScript must be enabled in your browser to display the table of contents.

Figure 1. NGCGUI imbedded into Axis

1. Overview

NGCGUI is a Tcl application to work with subroutines. It allows you to
have a conversational interface with LinuxCNC. You can organize the
subroutines in the order you need them to run and concatenate the
subroutines into one file for a complete part program.

NGCGUI can run as a standalone application or can be embedded in
multiple tab pages in the axis GUI

PYNGCGUI is an alternate, python implementation of ngcgui.

PYNGCGUI can run as a standalone application or can be embedded as
a tab page (with its own set of multiple subroutine tabs) in any
GUI that supports embedding of gladevcp applications axis, touchy, gscreen
and gmoccapy.

Using NGCGUI or PYNGCGUI:

Tab pages are provided for each subroutine specified in the INI file

New subroutines tab pages can be added on the fly using the
custom tab

The entry boxes can have a default value and an label that
are identified by special comments in the subroutine file

Subroutine invocations can be concatenated together to form a multiple step
program

Any single-file G code subroutine that conforms to ngcgui conventions can be used

Any gcmc (G code-meta-compiler) program that conforms to ngcgui conventions
for tagging variables can be used. (The gcmc executable must be installed
separately, see: http://www.vagrearg.org/content/gcmc)

Note

NGCGUI and PYNGCGUI implement the same functions and both process .ngc and .gcmc
files that conform to a few ngcgui-specific conventions. In this document,
the term NGCGUI generally refers to either application.

2. Demonstration Configurations

A number of demonstration configurations are located in the sim directory
of the Sample Configurations offered by the LinuxCNC configuration picker. The
configuration picker is on the system’s main menu:

CNC > LinuxCNC

Examples are included for the axis, touchy, gscreen, and gmoccapy.
These examples demonstrate both 3-axis (XYZ) cartesian configurations
(like mills) and lathe (XZ) setups. Some examples show the use of a
pop up keyboard for touch screen systems and other examples demonstrate
the use of files created for the gcmc (G code Meta Compiler) application.
The touchy examples also demonstrate incorporation of a gladevcp back plot
viewer (gremlin_view).

The simplest application is found as:

Sample Configurations/sim/axis/ngcgui /ngcgui_simple

A comprehensive example showing gcmc compatibility is at:

Sample Configurations/sim/axis/ngcgui/ngcgui_gcmc

A comprehensive example embedded as a gladevcp app and using gcmc is at:

To try a demonstration, select a sim configuration and start
the linuxCNC program.

If using the axis gui, press the E-Stop then Machine Power then Home All. Pick a ngcgui tab, fill in
any empty blanks with sensible values and press
Create Feature then Finalize. Finally press the Run button to watch it run. Experiment
by creating multiple features and features from different tab pages.

To create several subroutines concatinated into a single file, go to each tab
fill in the blanks, press Create Feature then using the arrow keys move any
tabs needed to put them in order. Now press Finalize and answer the prompt
to create

Other guis will have similar functionality but the buttons and names
may be different.

Note

Notes

The demonstration configs create tab pages for just a few of the provided
examples. Any gui with a custom tab can open any of the library
example subroutines or any user file if it is in the linuxCNC subroutine
path.

To see special key bindings, click inside an ngcgui tab page to get
focus and then presss Control-k.

The demonstration subroutines should run on the simulated
machine configurations included in the distribution. A user
should always understand the behavior and purpose of a program
before running on a real machine.

3. Library Locations

In linuxCNC installations installed from deb packages, the simulation configs
for ngcgui use symbolic links to non-user-writable LinuxCNC libraries for:

nc_files/ngcgui_lib ngcgui-compatible subfiles

nc_files/ngcgui_lib/lathe ngcgui-compatible lathe subfiles

nc_files/gcmc_lib ngcgui-gcmc-compatible programs

nc_files/ngcgui_lib/utilitysubs Helper subroutines

nc_files/ngcgui_lib/mfiles User M files

These libraries are located by ini file items that specify the search
paths used by linuxCNC (and ngcgui):

These are long lines (not continued on multiple lines)
that specify the directories used in a search patch. The
directory names are separated by colons (:). No spaces should
occur between directory names.

A user can create new directories for their own subroutines and
M-files and add them to the search path(s).

For example, a user could create directories from the terminal with the commands:

mkdir /home/myusername/mysubs
mkdir /home/myusername/mymfiles

And then create or copy system-provided files to these user-writable directories.
For instance, a user might create a ngcgui-compatible subfile named:

/home/myusername/mysubs/example.ngc

To use files in new directories, the ini file must be edited to include the new
subfiles and to augment the search path(s). For this example:

LinuxCNC (and ngcgui) use the first file found when searching
directories in the search path. With this behavior, you can
supersede an ngcgui_lib subfile by placing a subfile with an
identical name in a directory that is found earlier in the path
search. More information can be found in the INI chapter of the
Integrators Manual.

The optional truetype tracer items are used to specify an ngcgui-compatible tab page
that uses the application truetype-tracer. The truetype-tracer application must
be installed independently and located in the user PATH.

5.2. Embedding PYNGCGUI as a gladevcp tab page in a gui

The following INI file items go in the [DISPLAY] section for use with the
axis, gscreen, or touchy guis. (See additional sections below for additional
items needed)

The EMBED_TAB_LOCATION specifier is not used for the axis gui. While
pyngcgui can be embedded in axis, integration is more complete when using
ngcgui (using TKPKG = Ngcgui 1.0). To specify the EMBED_TAB_LOCATION
for other guis, see the DISPLAY Section of the INI
Configuration Chapter.

Note

The truetype tracer gui front-end is not currently available for gladevcp
applications.

5.3. Additional INI File items required for ngcgui or pyngcgui

The following INI file items go in the [DISPLAY] section for any gui
that embeds either ngcgui or pyngcgui.

NGCGUI_PREAMBLE = in_std.ngc - the preamble file to be added in front of the
subroutines. When concatenating several common subroutine invocations, this preamble
is only added once. For mm-based machines, use mm_std.ngc

This is an example of embedding NGCGUI into Axis. The subroutines need to be
in a directory specified by the [RS274NGC]SUBROUTINE_PATH. Some example
subroutines use other subroutines so check to be sure you have the
dependences, if any, in a SUBROUTINE_PATH directory. Some subroutines may
use custom Mfiles which must be in a directory specified by the
[RS274NGC]USER_M_PATH.

The Gcode-meta-compiler (gcmc) can include statements like:
include("filename.inc.gcmc");
By default, gcmc includes the current directory which, for linuxCNC, will be
the directory containing the linuxCNC ini file. Additional directories can be
prepended to the gcmc search order with the GCMC_INCLUDE_PATH item.

The above is not a complete axis gui INI — the items show are those
used by ngcgui. Many additional items are required by LinuxCNC to have
a complete INI file.

5.4. Truetype Tracer

Ngcgui_ttt provides support for truetype-tracer (v4). It creates an axis tab
page which allows a user to create a new ngcgui tab page after entering text
and selecting a font and other parameters. (Truetype-tracer must be installed
independently).

To embed ngcgui_ttt in axis, specify the following items in addition to ngcgui items:

An absolute path beginning with a "/" specifies a complete filesystem
location. A path beginning with a "~/" specifies a path starting
from the user’s home directory. A path beginning with "~username/"
specifies a path starting in username’s home directory.

Relative Paths

Relative paths are based on the startup directory which is the directory
containing the INI file. Using relative paths can facilitate relocation of
configurations but requires a good understanding of linux path specifiers.

./d0 is the same as d0, e.g., a directory named d0 in the startup directory
../d1 refers to a directory d1 in the parent directory
../../d2 refers to a directory d2 in the parent of the parent directory
../../../d3 etc.

Multiple directories can be specified with [RS274NGC]SUBROUTINE_PATH by
separating them with colons. The following example illustrates the format
for multiple directories and shows the use of relative and absolute paths.

This is one long line, do not continue on multiple lines. When linuxCNC and/or
ngcgui searches for files, the first file found in the search is used.

LinuxCNC (and ngcgui) must be able to find all subroutines including helper routines
that are called from within ngcgui subfiles. It is convenient to place
utility subs in a separate directory as indicated in the example above.

The distribution includes the ngcgui_lib directory and demo files for
preambles, subfiles, postambles and helper files. To modify the behavior
of the files, you can copy any file and place it in an earlier part of the
search path. The first directory searched is [DISPLAY]PROGRAM_PREFIX. You
can use this directory but it is better practice to create dedicated
directory(ies) and put them at the beginning of the [RS274NGC]SUBROUTINE_PATH.

In the following example, files in /home/myname/linuxcnc/mysubs will be found before
files in ../../nc_files/ngcgui_lib.

New users may inadvertently try to use files that are not structured to be
compatible with ngcgui requirements. Ngcgui will likely report numerous errors
if the files are not coded per its conventions. Good practice suggests that
ngcgui-compatible subfiles should be placed in a directory dedicated to that
purpose and that preamble, postamble, and helper files should be in separate
directory(ies) to discourage attempts to use them as subfiles. Files not intended
for use as subfiles can include a special comment: "(not_a_subfile)" so that
ngcgui will reject them automatically with a relevant message.

5.6. Summary of INI File item details for NGCGUI usage

Item: [RS274NGC]SUBROUTINE_PATH = dirname1:dirname2:dirname3 ...
Example: [RS274NGC]SUBROUTINE_PATH = ../../nc_files/ngcgui_lib:../../nc_files/ngcgui_lib/utilitysubs
Note: Optional, but very useful to organize subfiles and utility files
Item: [RS274NGC]USER_M_PATH = dirname1:dirname2:dirname3 ...
Example: [RS274NGC]USER_M_PATH = ../../nc_files/ngcgui_lib/mfiles
Note: Optional, needed to locate custom user mfiles
Item: [DISPLAY]EMBED_TAB_NAME = name to display on embedded tab page
Example: [DISPLAY]EMBED_TAB_NAME = Pyngcgui
Note: The entries: EMBED_TAB_NAME,EMBED_TAB_COMMAND,EMBED_TAB_LOCATION
define an embedded application for several linuxCNC guis
Item: [DISPLAY]EMBED_TAB_COMMAND = programname followed by arguments
Example: [DISPLAY]EMBED_TAB_COMMAND = gladevcp -x {XID} pyngcgui_axis.ui
Note: For gladevcp applications, see the <<cha:glade-vcp,GladeVCP Chapter>>
Item: [DISPLAY]EMBED_TAB_LOCATION = name_of_location
Example: [DISPLAY]EMBED_TAB_LOCATION = notebook_main
Note: See example INI files for possible locations
Not required for the axis gui
Item: [DISPLAY]PROGRAM_PREFIX = dirname
Example: [DISPLAY]PROGRAM_PREFIX = ../../nc_files
Note: Mandatory and needed for numerous linuxCNC functions
It is the first directory used in the search for files
item: [DISPLAY]TKPKG = Ngcgui version_number
Example: [DISPLAY]TKPKG = Ngcgui 1.0
Note: Required only for axis gui embedding, specifies loading of ngcgui axis tab pages
Item: [DISPLAY]NGCGUI_FONT = font_descriptor
Example: [DISPLAY]NGCGUI_FONT = Helvetica -12 normal
Note: Optional, font_descriptor is a tcl-compatible font specifier
with items for fonttype -fontsize fontweight
Default is: Helvetica -10 normal
Smaller font sizes may be useful for small screens
Larger font sizes may be helpful for touch screen applications
Item: [DISPLAY]NGCGUI_SUBFILE = subfile_filename
Example: [DISPLAY]NGCGUI_SUBFILE = simp.ngc
Example: [DISPLAY]NGCGUI_SUBFILE = square.gcmc
Example: [DISPLAY]NGCGUI_SUBFILE = ""
Note: Use one or more items to specify ngcgui-compatible
subfiles or gcmc programs that require a tab page on startup.
A "Custom" tab will be created when the filename is "".
A user can use a "Custom" tab to browse the file system
and identify preamble, subfile, and postamble files.
Item: [DISPLAY]NGCGUI_PREAMBLE = preamble_filename
Example: [DISPLAY]NGCGUI_PREAMBLE = in_std.ngc
Note: Optional, when specified, the file is prepended to a subfile.
Files created with "Custom" tab pages use the preamble specified
with the page.
Item: [DISPLAY]NGCGUI_POSTAMBLE = postamble_filename
Example: [DISPLAY]NGCGUI_POSTAMBLE = bye.ngc
Note: Optional, when specified, the file is appended to a subfiles.
Files created with "Custom" tab pages use the postamble specified
with the page.
Item: [DISPLAY]NGCGUI_OPTIONS = opt1 opt2 ...
Example: [DISPLAY]NGCGUI_OPTIONS = nonew noremove
Note: Multiple options are separated by blanks.
By default, ngcgui configures tab pages so that:
1) a user can make new tabs
2) a user can remove tabs (except for the last remaining one)
3) finalized files are automatically sent to linuxCNC
4) an image frame (iframe) is made available to display
an image for the subfile (if an image is provided)
5) the ngcgui result file sent to linuxCNC is terminated with
an m2 (and incurs m2 side-effects)
The options nonew, noremove, noauto, noiframe, nom2 respectively
disable these default behaviors.
By default, if an image (.png,.gif,jpg,pgm) file
is found in the same directory as the subfile, the
image is displayed in the iframe. Specifying
the noiframe option makes available additional buttons
for selecting a preamble, subfile, and postamble and
additional checkboxes. Selections of the checkboxes
are always available with special keys:
Ctrl-R Toggle "Retain values on Subfile read"
Ctrl-E Toggle "Expand subroutine"
Ctrl-a Toggle "Autosend"
(Ctrl-k lists all keys and functions)
If noiframe is specified and an image file is found,
the image is displayed in a separate window and
all functions are available on the tab page.
The NGCGUI_OPTIONS apply to all ngcgui tabs except that the
nonew, noremove, and noiframe options are not applicable
for "Custom" tabs. Do not use "Custom" tabs if you want
to limit the user's ability to select subfiles or create
additional tab pages.
Item: [DISPLAY]GCMC_INCLUDE_PATH = dirname1:dirname2:...
Example: [DISPLAY]GCMC_INCLUDE_PATH = /home/myname/gcmc_includes:/home/myname/gcmc_includes2
Note: Optional, each directory will be included when gcmc is invoked
using the option: --include dirname

6. File Requirements for NGCGUI Compatibility

6.1. Single-File Gcode (.ngc) Subroutine Requirements

An NGCGUI-compatible subfile contains a single subroutine definition. The name
of the subroutine must be the same as the filename (not including the .ngc
suffix). LinuxCNC supports named or numbered subroutines, but only named
subroutines are compatible with NGCGUI. For more information see the
O-Codes Chapter.

The first non-comment line should be a sub statement.
The last non-comment line should be a endsub statement.

The body of the subroutine should begin with a set of statements that define
local named parameters for each positional parameter expected for the
subroutine call. These definitions must be consecutive beginning with #1 and
ending with the last used parameter number. Definitions must be provided for
each of these parameters (no omissions).

Parameter Numbering

#<xparm> = #1
#<yparm> = #2
#<zparm> = #3

LinuxCNC considers all numbered parameters in the range #1 thru #30 to be calling
parameters so ngcgui provides entry boxes for any occurence of parameters in
this range. It is good practice to avoid use of numbered parameters #1 through
#30 anywhere else in the subroutine. Using local, named parameters is
recommended for all internal variables.

Each defining statement may optionally include a special comment and a default
value for the parameter.

If a default_value is provided, it will be entered in the entry box
for the parameter on startup.

If comment_text is included, it will be used to identify the input
instead of the parameter name.

Global Named Parameters

Notes on global named parameters and ngcgui:

(global named parameters have a leading underscore in the name, like
#<_someglobalname>)

As in many programming languages, use of globals is powerful but can often lead
to unexpected consequences. In LinuxCNC, existing global named parameters will be
valid at subroutine execution and subroutines can modify or create global named
parameters.

Passing information to subroutines using global named parameters is discouraged
since such usage requires the establishment and maintenance of a well-defined
global context that is difficult to maintain. Using numbered parameters #1
thru #30 as subroutine inputs should be sufficient to satisfy a wide range of
design requirements.

While input global named parameters are discouraged, linuxCNC subroutines must use
global named parameters for returning results. Since ngcgui-compatible
subfiles are aimed at gui usage, return values are not a common requirement.
However, ngcgui is useful as a testing tool for subroutines which do return
global named parameters and it is common for ngcgui-compatible subfiles to call
utility subroutine files that return results with global named parameters.

To support these usages, ngcgui ignores global named parameters that include a
colon (:) character in their name. Use of the colon (:) in the name prevents
ngcgui from making entryboxes for these parameters.

In the above example, the utility subroutine will be found in a separate file
named helper.ngc. The helper routine returns a result in a global
named parameter named #<_helper:answer.

For good practice, the calling subfile immediately localizes the result for use
elsewhere in the subfile and the global named parameter used for returning the
result is nullified in an attempt to mitigate its inadvertent use elsewhere in
the global context. (A nullification value of 0.0 may not always be a good
choice).

Ngcgui supports the creation and concatenation of multiple features for a
subfile and for multiple subfiles. It is sometimes useful for subfiles to
determine their order at runtime so ngcgui inserts a special global parameter
that can be tested within subroutines. The parameter is named #<_feature:>.
Its value begins with a value of 0 and is incremented for each added feature.

Additional Features

A special info comment can be included anywhere in an ngcgui-compatible
subfile. The format is:

(info: info_text)

The info_text is displayed near the top of the ngcgui tab page in axis.

Files not intended for use as subfiles can include a special comment
so that ngcgui will reject them automatically with a relevant message.

(not_a_subfile)

An optional image file (.png,.gif,.jpg,.pgm) can accompany a subfile. The
image file can help clarify the parameters used by the subfile. The image file
should be in the same directory as the subfile and have the same name with an
appropriate image suffix, e.g. the subfile example.ngc could be accompanied by an
image file examp.png. Ngcgui attempts to resize large images by subsampling
to a size with maximum width of 320 and maximum height of 240 pixels.

None of the conventions required for making an ngcgui-compatible subfile
preclude its use as general purpose subroutine file for LinuxCNC.

The LinuxCNC distribution includes a library (ngcgui_lib directory) that
includes both example ngcgui-compatible subfiles and utility files
to illustrate the features of LinuxCNC subroutines and ngcgui usage.
Another libary (gcmc_lib) provides examples for subroutine files for
the Gcode meta compiler (gcmc)

Additional user sumitted subroutines can be found on the Forum in the
Subroutines Section.

6.2. Gcode-meta-compiler (.gcmc) file requirements

Files for the Gcode-meta-compiler (gcmc) are read by ngcgui and it
creates entry boxes for variables tagged in the file. When a feature
for the file is finalized, ngcgui passes the file as input to the gcmc
compiler and, if the compile is successful, the resulting gcode file
is sent to linuxCNC for execution. The resulting file is formatted as
single-file subroutine; .gcmc files and .ngc files can be intermixed
by ngcgui.

The variables identified for inclusion in ngcgui are tagged with lines
that will appear as comments to the gcmc compiler.

For these examples, the entry box for varname1 will have no default,
the entry box for varname2 will have a default of value2, and the
entry box for varname 3 will have a default of value 3 and a label
label3 (instead of varname3). The default values must be numbers.

To make it easier to modify valid lines in a gcmc file, alternate
tag line formats accepted. The alternate formats ignore trailing
semicolons (;) and trailing comment markers (//) With this provision,
it is often makes it possible to just add the //ngcgui: tag to
existing lines in a .gcmc file.

Alternate variable tag formats

//ngcgui: varname2 = value2;
//ngcgui: varname3 = value3; //, label3;

Examples:

//ngcgui: feedrate = 10;
//ngcgui: xl = 0; //, x limit

An info line that will appear at the top of a tab page may be optionally
included with a line tagged as:

Info tag

//ngcgui: info: text_to_appear_at_top_of_tab_page

When required, options can be passed to the gcmc compiler with a line tagged:

A gcmc program by default uses metric mode. The mode can be
set to inches with the option setting:

//ngcgui: --imperial

A preamble file, if used, can set a mode (g20 or g21) that
conflicts with the mode used by a gcmc file. To ensure that
the gcmc program mode is in effect, include the following
statement in the .gcmc file:

include("ensure_mode.gcmc")

and provide a proper path for gcmc include_files in the ini file,
for example:

[DISPLAY]
GCMC_INCLUDE_PATH = ../../nc_files/gcmc_lib

7. DB25 Example

The following shows the DB25 subroutine. In the first photo you see where you
fill in the blanks for each variable.

This photo shows the backplot of the DB25 subroutine.

This photo shows the use of the new button and the custom tab to create
three DB25 cutouts in one program.