summaryrefslogtreecommitdiff
path: root/docs/src/gui/ngcgui_es.txt
blob: 4d40ce5ab724b3b420cf929cb9353cbb8e5ab058 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
= NGCGUI

[[cha:ngcgui]] (((NGCGUI)))

////
ATTENTION TRANSLATORS before translating this document copy the base document
into this copy to get the latest version. Untranslated documents are not kept
up to date with the English documents. 

Do not translate anchors or links, translate only the text of a link after the
comma.
Anchor [[anchor-name]]
Link <<anchor-name,text after the comma can be translated>>

Make sure the documents build after translating.
////

image::images/ngcgui.png[]

== Overview
    
* 'NGCGUI' is a utility for using LinuxCNC subroutines.
* 'NGCGUI' can run as a standalone application or be embedded in
   multiple tab pages in the axis gui
* Multiple copies of the same subroutine can be created
* Subroutines can be concatenated together to form a complete multiple
  step program
* New subroutines can be added on the fly

NGCGUI is a powerful tool for building g-code programs from subroutines
on the fly.
Subroutines can be concatenated to build a complete program. Multiple
instances of a subroutine can be used to perform the same task in different
locations on the part. Any valid g-code can be used in the subroutine.

== Demo Configs

Three demo configurations are are located in the sim directory of the
LinuxCNC configuration picker. The configuration picker is on the main menu
Applications > CNC > LinuxCNC.

* 'ngcgui' - a comprehensive example that contains these subroutines
** 'simp' - a simple subroutine example that creates two circles
** 'xyz' - creates a box based on two opposite corners
** 'iquad' - creates an internal quadrilateral
** 'db25' - creates a DB25 plug cutout
** 'ihex' - creates an interal hexagon
** 'gosper' - a recursion demo
** 'Custom' - load other ngcgui-compatible subfiles
** 'ttt' - True Type Tracer creates text for engraving

* 'ngcgui-lathe' - an example with lathe subroutines
** 'id' - bores the inside diameter
** 'od' - turns the outside diameter
** 'taper-od' - turns a taper on the outside diameter
** 'Custom' - creates custom tabs

* 'ngcgui-simple' - a simple example
** 'simp' - a simple subroutine example that creates two circles
** 'xyz' - creates a box based on two opposite corners

To view the demonstration subroutines press the 'E-Stop' 
image:images/tool_estop.gif[] then 'Machine Power' 
image:images/tool_power.gif[] then 'Home All'. Pick a ngcgui tab and press
'Create Feature' then 'Finalize'. Now press the 'Run'
image:images/tool_run.gif[] button to watch it run.

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

== Libraries

The simulation configs for ngcgui use links to non-user-writable
LinuxCNC libraries for:

* 'ngcgui-compatible subfiles' - ngcgui_lib
* 'Helper subroutines' - ngcgui_lib/utilitysubs
* 'User M files' - ngcgui_lib/mfiles

These libraries are defined by the ini file items:

----
[RS274NGC]
SUBROUTINE_PATH = ../../../nc_files/ngcgui_lib:../../../nc_files/ngcgui_lib/utilitysubs
USER_M_PATH     = ../../../nc_files/ngcgui_lib/mfiles
----

[NOTE]
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 (:)

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.

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

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

----
/home/myusername/mysubs/example.ngc
----

The ini file must be edited to include new subfiles and to
augment the path(s).  For this example:

----
[RS274NGC]
SUBROUTINE_PATH = /home/myusername/mysubs:../../../nc_files/ngcgui_lib:../../../nc_files/ngcgui_lib/utilitysubs
USER_M_PATH     = /home/myusername/mymfiles:../../../nc_files/ngcgui_lib/mfiles

[DISPLAY]
NGCGUI_SUBFILE = example.ngc
----

LinuxCNC and ngcgui use the first file found when searching
directories in a 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.


== Embedding NGCGUI in Axis

Several NGCGUI examples are included with LinuxCNC and are located in the sim/ngcgui
directory.

=== INI File

The following INI file items for NGCGUI go in the [DISPLAY] section.

* 'TKPKG = Ngcgui 1.0' - the main NGCGUI package (must precede Ngcguittt)
* 'TKPKG = Ngcguittt 1.0' - the True Type Tracer package for generating text
   for engraving.
* 'NGCGUI_FONT = Helvetica -12 normal' - specifices the font
* 'NGCGUI_PREAMBLE = in_std.ngc' - the preamble file to be added in front of the
  subroutines. When concatenating several subroutines this is only added once.
* 'NGCGUI_SUBFILE = simp.ngc' - creates a tab from the named subroutine
* 'NGCGUI_SUBFILE = ""' - creates a custom tab
* 'NGCGUI_OPTIONS = opt1 opt2 ...' - NGCGUI options
** 'nonew' - disallow making a new custom tab
** 'noremove' - disallow removing any tab page
** 'noauto' - no auto send (makeFile, then manually send)
** 'noiframe' - no internal image, image on separate top level
* 'TTT = truetype-tracer' - the truetype tracer program
* 'TTT_PREAMBLE = in_std.ngc' - Optional, specifies filename for preamble used for
   ttt created subfiles

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.

.Sample INI
----
[RS274NGC]
SUBROUTINE_PATH   = ../../../nc_files/ngcgui_lib:../../../ngcgui_lib/utilitysubs
USER_M_PATH       = ../../../nc_files/ngcgui_lib/mfiles

[DISPLAY]
TKPKG             = Ngcgui    1.0
TKPKG             = Ngcguittt 1.0
# Ngcgui must precede Ngcguittt

NGCGUI_FONT       = Helvetica -12 normal
# specify filenames only, files must be in [RS274NGC]SUBROUTINE_PATH
NGCGUI_PREAMBLE   = in_std.ngc
NGCGUI_SUBFILE    = simp.ngc
NGCGUI_SUBFILE    = xyz.ngc
NGCGUI_SUBFILE    = iquad.ngc
NGCGUI_SUBFILE    = db25.ngc
NGCGUI_SUBFILE    = ihex.ngc
NGCGUI_SUBFILE    = gosper.ngc
# specify "" for a custom tab page
NGCGUI_SUBFILE    = ""
#NGCGUI_SUBFILE   = "" use when image frame is specified if
#                      opening other files is required
#                      images will be put in a top level window
NGCGUI_OPTIONS    =
#NGCGUI_OPTIONS   = opt1 opt2 ...
# opt items:
#   nonew      -- disallow making a new custom tab
#   noremove   -- disallow removing any tab page
#   noauto     -- no auto send (makeFile, then manually send)
#   noiframe   -- no internal image, image on separate top level

TTT               = truetype-tracer
TTT_PREAMBLE      = in_std.ngc

PROGRAM_PREFIX    = ../../nc_files
----

=== 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:
....
Item:    [DISPLAY]TKPKG = Ngcgui_ttt version_number
Example: [DISPLAY]TKPKG = Ngcgui_ttt 1.0
Note:    Mandatory, specifies loading of ngcgui_ttt in an axis tab page named ttt.
         Must follow the TKPKG = Ngcgui item.

Item:    [DISPLAY]TTT = path_to_truetype-tracer
Example: [DISPLAY]TTT = truetype-tracer
Note:    Optional, if not specified, attempt to use /usr/local/bin/truetype-tracer.
         Specify with absolute pathname or as a simple executable name
         in which case the user PATH environment will used to find the program.

Item:    [DISPLAY]TTT_PREAMBLE = preamble_filename
Example: [DISPLAY]TTT_PREAMBLE = in_std.ngc
Note:    Optional, specifies filename for preamble used for ttt created subfiles.
....

=== INI Examples

Ngcgui uses the EMC search path to find files.

The search path begins with the standard directory specified by:

  [DISPLAY]PROGRAM_PREFIX

followed by multiple directories specfied by:

  [RS274NGC]SUBROUTINE_PATH

.Directories
Directories may be specifed as absolute paths or relative paths.
....
Example: [DISPLAY]PROGRAM_PREFIX = /home/myname/emc2/nc_files
Example: [DISPLAY]PROGRAM_PREFIX = ~/emc2/nc_files
Example: [DISPLAY]PROGRAM_PREFIX = ../../../nc_files
....

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.

`Example: [RS274NGC]SUBROUTINE_PATH = ../../../nc_files/ngcgui_lib:../../../nc_files/ngcgui_lib/utilitysubs:/tmp/tmpngc`

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

EMC (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/emc2/mysubs will be found before
files in ../../../nc_files/ngcgui_lib.

`Example: [RS274NGC]SUBROUTINE_PATH = /home/myname/emc2/mysubs:../../../nc_files/ngcgui_lib:../../../nc_files/ngcgui_lib/utilitysubs`

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.

To embed ngcgui in axis, specify the following items in the inifile:
....
Item:    [DISPLAY]PROGRAM_PREFIX = dirname
Example: [DISPLAY]PROGRAM_PREFIX = ../../../nc_files
Note:    Mandatory and needed for numerous emc functions
         It is the first directory used in the search for files

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

otem:    [DISPLAY]TKPKG=Ngcgui version_number
Example: [DISPLAY]TKPKG=Ngcgui 1.0
Note:    Mandatory, 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

Item:    [DISPLAY]NGCGUI_SUBFILE = subfile_filename
Example: [DISPLAY]NGCGUI_SUBFILE = simp.ngc
Example: [DISPLAY]NGCGUI_SUBFILE = xyz.ngc
Example: [DISPLAY]NGCGUI_SUBFILE = ""
Note:    Use one or more items to specify ngcgui-compatible
         subfiles that require an axis 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 all subfiles.
         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 all 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 axis
            4) an image frame (iframe) is made available to display
               an image for the subfile

         The options nonew, noremove, noauto, noiframe 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.
....

== 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
<<cha:O-Codes,O-Codes>> Chapter.

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

.examp.ngc:
----
o<examp> sub
  BODY_OF_SUBROUTINE
o<examp> endsub
----

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.

.Statement Prototype
----
#<vname> = #n (=default_value)
or
#<vname> = #n (comment_text)
or
#<vname> = #n (=default_value comment_text)
----

.Parameter Examples
----
#<xparm> = #1 (=0.0)
#<yparm> = #2 (Ystart)
#<zparm> = #3 (=0.0 Z start setting)
----

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 (#<_globalname>) and ngcgui:

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.

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

Ngcgui includes some support for global named input parameters but usage
is deprecated and not documented here.

While input global named parameters are discouraged, emc 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.

.Global Named Parameters
----
o<examp> sub
...
#<_examp:result> = #5410       (return the current tool diameter)
...
o<helper> call [#<x1>] [#<x2>] (call a subroutine)
#<xresult> = #<_helper:answer> (localize immediately the helper result)
#<_helper:answer> = 0.0        (nullify global named parameter used by subroutine)
...
o<examp> endsub
----

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 examp.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.

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

== DB25 Example

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

image::images/ngcgui-db25-1.png[]

This photo shows the backplot of the DB25 subroutine.

image::images/ngcgui-db25-2.png[]

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

image::images/ngcgui-db25-3.png[]