ini-config.txt
1 [[cha:ini-configuration]] 2 3 = INI Configuration 4 5 == The INI File Components 6 7 A typical INI file follows a rather simple layout that includes; 8 9 * comments 10 * sections 11 * variables 12 13 Each of these elements is separated on single lines. Each end of line 14 or newline character creates a new element. 15 16 (((INI File, Comments))) 17 18 === Comments 19 20 A comment line is started with a ; or a # mark. When the ini reader 21 sees either of these marks at the start a line, the rest of the line is 22 ignored by the software. Comments can be used to describe what an INI 23 element will do. 24 25 ---- 26 ; This is my mill configuration file. 27 # I set it up on January 12, 2012 28 ---- 29 30 Comments can also be used to 'turn off' a variable. This makes it easier 31 to pick between different variables. 32 33 ---- 34 DISPLAY = axis 35 # DISPLAY = touchy 36 ---- 37 38 In this list, the DISPLAY variable will be set to axis because the 39 other one is commented out. If someone carelessly edits a list like 40 this and leaves two of the lines uncommented, the first one encountered 41 will be used. 42 43 Note that inside a variable, the "#" and ";" characters do not denote 44 comments: 45 46 ---- 47 INCORRECT = value # and a comment 48 49 # Correct Comment 50 CORRECT = value 51 ---- 52 53 === Sections 54 55 Related parts of an ini file are separated into sections. 56 A section name is enclosed in brackets like this '[THIS_SECTION]' 57 The order of sections is unimportant. Sections begin at the section 58 name and end at the next section name. 59 60 The following sections are used by LinuxCNC: 61 62 * '[<<sec:emc-section,EMC>>]' general information 63 * '[<<sec:display-section,DISPLAY>>]' settings related to the graphical user interface 64 * '[<<sec:filter-section,FILTER>>]' settings input filter programs 65 * '[<<sec:rs274ngc-section,RS274NGC>>]' settings used by the g-code interpreter 66 * '[<<sec:emcmot-section,EMCMOT>>]' settings used by the real time motion controller 67 * '[<<sec:task-section,TASK>>]' settings used by the task controller 68 * '[<<sec:hal-section,HAL>>]' specifies .hal files 69 * '[<<sec:halui-section,HALUI>>]' MDI commands used by HALUI 70 * '[<<sec:applications-section,APPLICATIONS>>]' Other applications to be started by LinuxCNC 71 * '[<<sec:traj-section,TRAJ>>]' additional settings used by the real time motion controller 72 * '[<<sec:joint-section,JOINT_n>>]' individual joint variables 73 * '[<<sec:axis-section,AXIS_n>>]' individual axis variables 74 * '[<<sec:kins-section,KINS>>]' kinematics variables 75 76 * '[<<sec:emcio-section,EMCIO>>]' settings used by the I/O Controller 77 78 === Variables 79 80 A variable line is made up of a variable name, an equals sign (=), and 81 a value. Everything from the first non-white space character after the 82 = up to the end of the line is passed as the value, so you can embed 83 spaces in string symbols if you want to or need to. A variable name is 84 often called a keyword. 85 86 .Variable Example 87 ---- 88 MACHINE = My Machine 89 ---- 90 91 A variable line may be extended to multiple lines with a terminal backslash (\) 92 character. A maximum of MAX_EXTEND_LINES (==20) are allowed. There must be no 93 whitespace following the trailing backslash character. 94 95 Section identifiers may not be extended to multiple lines. 96 97 .Variable with Line extends Example 98 ---- 99 APP = sim_pin \ 100 ini.0.max_acceleration \ 101 ini.1.max_acceleration \ 102 ini.2.max_acceleration \ 103 ini.0.max_velocity \ 104 ini.1.max_velocity \ 105 ini.2.max_velocity 106 ---- 107 108 The following sections detail each section of the configuration file, 109 using sample values for the configuration lines. 110 111 Variables that are used by LinuxCNC must always use the section 112 names and variable names as shown. In the following example the variable 113 'MACHINE' is assigned the value 'My Machine'. 114 115 [[sub:custom-variables]] 116 117 === Custom Sections and Variables 118 119 Most sample configurations use custom sections and variables to put all of the 120 settings into one location for convenience. 121 122 To add a custom variable to an existing LinuxCNC section, simply include 123 the variable in that section. 124 125 .Custom Variable Example 126 ---- 127 [JOINT_0] 128 TYPE = LINEAR 129 ... 130 SCALE = 16000 131 ---- 132 133 To introduce a custom section with its own variables, add the section 134 and variables to the INI file. 135 136 .Custom Section Example 137 ---- 138 [PROBE] 139 Z_FEEDRATE = 50 140 Z_OFFSET = 12 141 Z_SAFE_DISTANCE = -10 142 ---- 143 144 To use the custom variables in your HAL file, put the section and 145 variable name in place of the value. 146 147 .HAL Example 148 ---- 149 setp offset.1.offset [PROBE]Z_OFFSET 150 setp stepgen.0.position-scale [JOINT_0]SCALE 151 ---- 152 153 [NOTE] 154 The value stored in the variable must match the type specified by the 155 component pin. 156 157 To use the custom variables in G-code, use the global variable syntax 158 `#<_ini[section]variable>`. The following example shows a simple 159 Z-axis touch-off routine for a router or mill using a probe plate. 160 161 .G-code Example 162 [source,{ngc}] 163 --------------------------------------------------------------------- 164 G91 165 G38.2 Z#<_ini[probe]z_safe_distance> F#<_ini[probe]z_feedrate> 166 G90 167 G1 Z#5063 168 G10 L20 P0 Z#<_ini[probe]z_offset> 169 --------------------------------------------------------------------- 170 171 [NOTE] 172 ==== 173 Referring to INI-file variables from G-code is currently an experimental 174 feature. To enable it, specify the appropriate FEATURES bitmask value in 175 the <<sec:rs274ngc-section,RS274NGC>> section of the INI file, e.g. 176 177 [source,{ini}] 178 --------------------------------------------------------------------- 179 [RS274NGC] 180 ... 181 FEATURES=4 182 --------------------------------------------------------------------- 183 184 See <<remap:ini-features,Optional Interpreter Features>> in the 185 <<cha:remap,Remap Extending G-Code>> chapter for details. 186 ==== 187 188 189 === Include Files 190 191 An INI file may include the contents of another file by using a #INCLUDE 192 directive. 193 194 .#INCLUDE Format 195 ---- 196 #INCLUDE filename 197 ---- 198 199 The filename can be specified as: 200 201 * a file in the same directory as the INI file 202 * a file located relative to the working directory 203 * an absolute file name (starts with a /) 204 * a user-home-relative file name (starts with a ~) 205 206 Multiple #INCLUDE directives are supported. 207 208 .#INCLUDE Examples 209 ---- 210 #INCLUDE joint_0.inc 211 #INCLUDE ../parallel/joint_1.inc 212 #INCLUDE below/joint_2.inc 213 #INCLUDE /home/myusername/myincludes/display.inc 214 #INCLUDE ~/linuxcnc/myincludes/rs274ngc.inc 215 ---- 216 217 The #INCLUDE directives are supported for one level of expansion only -- an 218 included file may not include additional files. The recommended file extension 219 is .inc. Do not use a file extension of .ini for included files. 220 221 222 == INI File Sections 223 224 [[sec:emc-section]](((INI File, EMC Section))) 225 226 === [EMC] Section 227 228 * 'VERSION = 1.1' - The version number for the configuration. Any value other 229 than 1.1 will cause the configuration checker to run and try to update the 230 configuration to the new style joint axes type of configuration. 231 232 * 'MACHINE = My Controller' - This is the name of the controller, which is 233 printed out at the top of most graphical interfaces. You can put whatever 234 you want here as long as you make it a single line long. 235 236 * 'DEBUG = 0' - Debug level 0 means no messages will be printed when LinuxCNC is 237 run from a <<faq:terminal,terminal>>. Debug flags are usually only useful to 238 developers. See src/emc/nml_intf/debugflags.h for other settings. 239 240 [[sec:display-section]](((INI File, DISPLAY Section))) 241 242 === [DISPLAY] Section 243 244 Different user interface programs use different options, and not every 245 option is supported by every user interface. The main two interfaces 246 for LinuxCNC are AXIS and Touchy. There are several newer interfaces, 247 like gmoccapy and gscreen. Axis is an interface for use with normal 248 computer and monitor, Touchy is for use with touch screens. Gmoccapy 249 can be used both ways and offers also many connections for hardware controls. 250 Descriptions of the interfaces are in the Interfaces section of the 251 User Manual. 252 253 * 'DISPLAY = axis' - The name of the user interface to use. Valid options 254 may include: 'axis', 'touchy', 'gmoccapy', 'gscreen', 'tklinuxcnc' 255 256 * 'POSITION_OFFSET = RELATIVE' - The coordinate system (RELATIVE or MACHINE) 257 to show on the DRO when the user interface starts. The RELATIVE coordinate 258 system reflects the G92 and G5x coordinate offsets currently in effect. 259 260 * 'POSITION_FEEDBACK = COMMANDED' - The coordinate value (COMMANDED or ACTUAL) 261 to show on the DRO when the user interface starts. In Axis this can be changed 262 from the View menu. The COMMANDED position is the position requested by 263 LinuxCNC. The ACTUAL position is the feedback position of the motors if they 264 have feedback like most servo systems. Typically the COMMANDED value is used. 265 266 * 'DRO_FORMAT_MM = %+08.6f' - Over-ride the default DRO formatting in metric 267 mode. (normally 3 decimal places, padded with spaces to 6 digits to the left) 268 the example above will pad with zeros, display 6 decimal digits and force 269 display of a + sign for positive numbers. Formatting follows Python practice. 270 https://docs.python.org/2/library/string.html#format-specification-mini-language 271 an error will be raised if the format can not accept a floating-point value. 272 273 * 'DRO_FORMAT_IN = % 4.1f' - Over-ride the default DRO formatting in imperial 274 mode. (normally 4 decimal places, padded with spaces to 6 digits to the left) 275 the example above will display only one decimal digit. Formatting follows 276 Python practice. 277 https://docs.python.org/2/library/string.html#format-specification-mini-language 278 An error will be raised if the format can not accept a floating-point value. 279 280 * 'MAX_FEED_OVERRIDE = 1.2' - The maximum feed override the user may select. 281 1.2 means 120% of the programmed feed rate. 282 283 * 'MIN_SPINDLE_OVERRIDE = 0.5' - The minimum spindle override the user may 284 select. 0.5 means 50% of the programmed spindle speed. (This is used to 285 set the minimum spindle speed). 286 287 * 'MAX_SPINDLE_OVERRIDE = 1.0' - The maximum spindle override the user may 288 select. 1.0 means 100% of the programmed spindle speed. 289 290 * 'DEFAULT_SPINDLE_SPEED = 100' - The default spindle RPM when the spindle 291 is started in manual mode. if this setting is not present, this 292 defaults to 1 RPM for AXIS and 300 RPM for gmoccapy. 293 294 * 'PROGRAM_PREFIX = ~/linuxcnc/nc_files' - The default location for g-code 295 files and the location for user-defined M-codes. This location is searched 296 for the file name before the subroutine path and user M path if specified 297 in the [RS274NGC] section. 298 299 * 'INTRO_GRAPHIC = emc2.gif' - The image shown on the splash screen. 300 301 * 'INTRO_TIME = 5' - The maximum time to show the splash screen, in seconds. 302 303 * 'CYCLE_TIME = 0.05' - Cycle time in seconds that display will sleep between 304 polls. 305 306 [NOTE] 307 The following [DISPLAY] items are used by GladeVCP, see the 308 <<gladevcp:embeding-tab,embedding a tab>> section of the GladeVCP Chapter. 309 310 * 'EMBED_TAB_NAME=GladeVCP demo' 311 312 * 'EMBED_TAB_COMMAND=halcmd loadusr -Wn gladevcp gladevcp -c gladevcp -x {XID} -u ./gladevcp/hitcounter.py ./gladevcp/manual-example.ui' 313 314 315 [NOTE] 316 The following [DISPLAY] items are for the AXIS interface only, see the 317 <<cha:axis-gui,AXIS GUI>> document for details. 318 Many of them are used also from gmoccapy, see the 319 <<cha:gmoccapy,gmoccapy>> document for details. 320 321 * 'DEFAULT_LINEAR_VELOCITY = .25' - The default velocity for linear jogs, in , 322 <<sec:traj-section,machine units>> per second. 323 324 * 'MIN_VELOCITY = .01' - The approximate lowest value the jog slider. 325 326 * 'MAX_LINEAR_VELOCITY = 1.0' - The maximum velocity for linear jogs, in machine units per second. 327 328 * 'MIN_LINEAR_VELOCITY = .01' - The approximate lowest value the jog slider. 329 330 * 'DEFAULT_ANGULAR_VELOCITY = .25' - The default velocity for angular jogs, in machine units per second. 331 332 * 'MIN_ANGULAR_VELOCITY = .01' - The approximate lowest value the angular jog slider. 333 334 * 'MAX_ANGULAR_VELOCITY = 1.0' - The maximum velocity for angular jogs, in machine units per second. 335 336 * 'INCREMENTS = 1 mm, .5 in, ...' - Defines the increments available for incremental jogs. 337 The INCREMENTS can be used to override the default. 338 The values can be decimal numbers (e.g., 0.1000) or fractional numbers (e.g., 1/16), 339 optionally followed by a unit (cm, mm, um, inch, in or mil). 340 If a unit is not specified the machine unit is assumed. 341 Metric and imperial distances may be mixed: 342 INCREMENTS = 1 inch, 1 mil, 1 cm, 1 mm, 1 um is a valid entry. 343 344 * 'GRIDS = 10 mm, 1 in, ...' - Defines the preset values for grid lines. 345 The value is interpreted the same way as 'INCREMENTS'. 346 347 * 'OPEN_FILE = /full/path/to/file.ngc' - The file to show in the preview plot when AXIS starts. Use 348 a blank string "" and no file will be loaded at start up. gmoccapy will not use this setting, as it 349 offers a coresponding entry on its settings page. 350 351 * 'EDITOR = gedit' - The editor to use when selecting File > Edit to edit the G code 352 from the AXIS menu. This must be configured for this menu item to 353 work. Another valid entry is gnome-terminal -e vim. This entry does not apply to gmoccapy, as gmoccapy 354 has an integrated editor. 355 356 * 'TOOL_EDITOR = tooledit' - The editor to use when editing the tool table (for example by 357 selecting "File > Edit tool table..." in Axis). Other valid 358 entries are "gedit", "gnome-terminal -e vim", and "gvim". This entry does not apply to gmoccapy, as gmoccapy 359 has an integrated editor. 360 361 * 'PYVCP = /filename.xml' - The PyVCP panel description file. See the 362 <<cha:pyvcp,PyVCP Chapter>> for more information. 363 364 * 'LATHE = 1' - Any non-empty value (including "0") causes axis to use "lathe mode" with a top view and with Radius and Diameter on the DRO. 365 366 * 'BACK_TOOL_LATHE = 1' - Any non-empty value (including "0") causes axis to use "back tool lathe mode" with inverted X axis. 367 368 * 'FOAM = 1' - Any non-empty value (including "0") causes axis to change the display for foam-cutter mode. 369 370 * 'GEOMETRY = XYZABCUVW' - Controls the preview and backplot of rotary motion. This item consists 371 of a sequence of axis letters, optionally preceded by a "-" sign. 372 This sequence specifies the order in which the effect 373 of each axis is applied, with a "-" inverting the sense of the 374 rotation. 375 The proper GEOMETRY string depends on the machine configuration and 376 the kinematics used to control it. The example string GEOMETRY=XYZBCUVW 377 is for a 5-axis machine where kinematics causes UVW to move in the 378 coordinate system of the tool and XYZ to move in the coordinate system 379 of the material. The order of the letters is important, because it 380 expresses the order in which the different transformations are applied. 381 For example rotating around C then B is different than rotating around 382 B then C. Geometry has no effect without a rotary axis. 383 Foam-cutting machines (FOAM = 1) should specify "XY;UV" or leave the value 384 blank even though this value is presently ignored in foam-cutter mode. A 385 future version may define what ";" means, but if it does "XY;UV" will mean 386 the same as the current foam default. 387 388 * 'ARCDIVISION = 64' - Set the quality of preview of arcs. Arcs are previewed by dividing 389 them into a number of straight lines; a semicircle is divided into 390 *ARCDIVISION* parts. Larger values give a more accurate preview, but 391 take longer to 392 load and result in a more sluggish display. Smaller values give a less 393 accurate preview, but take less time to load and may result in a faster 394 display. The default value of 64 means a circle of up to 3 inches will 395 be displayed to within 1 mil (.03%). 396 397 * 'MDI_HISTORY_FILE =' - The name of a local MDI history file. If this is not specified Axis 398 will save the MDI history in *.axis_mdi_history* in the user's home 399 directory. This is useful if you have multiple configurations on one 400 computer. 401 402 * 'JOG_AXES =' - The order in which jog keys are assigned to axis letters. The left and right arrows are assigned to the first axis letter, up and down to the second, page up/page down to the third, and left and right bracket to the fourth. If unspecified, the default is determined from the [TRAJ]COORDINATES, [DISPLAY]LATHE and [DISPLAY]FOAM values. 403 404 * 'JOG_INVERT =' - For each axis letter, the jog direction is inverted. The default is "X" for lathes and blank otherwise. 405 406 [NOTE] 407 The settings for 'JOG_AXES' and 'JOG_INVERT' apply to world mode jogging by axis coordinate letter 408 and are in effect while in world mode after successful homing. When operating in joint 409 mode prior to homing, keyboard jog keys are assigned in a fixed sequence: left/right: joint0, 410 up/down: joint1, page up/page down: joint2, left/right bracket: joint3 411 412 413 * 'USER_COMMAND_FILE = mycommands.py' -- The name of an optional, configuration-specific 414 python file sourced by the axis gui instead of the user-specific file `~/.axisrc`. 415 416 [NOTE] 417 The following [DISPLAY] item is used by the TKLinuxCNC interface only. 418 419 * 'HELP_FILE = tklinucnc.txt' - Path to help file. 420 421 [[sec:filter-section]](((INI File, FILTER Section))) 422 423 === [FILTER] Section 424 425 AXIS and gmoccapy have the ability to send loaded files through a filter program. 426 This filter can do any desired task: Something as simple as making sure 427 the file ends with M2, or something as complicated as detecting whether 428 the input is a depth image, and generating g-code to mill the shape it 429 defines. The [FILTER] section of the ini file controls how filters 430 work. First, for each type of file, write a PROGRAM_EXTENSION line. 431 Then, specify the program to execute for each type of file. This 432 program is given the name of the input file as its first argument, and 433 must write RS274NGC code to standard output. This output is what will 434 be displayed in the text area, previewed in the display area, and 435 executed by LinuxCNC when Run. 436 437 * 'PROGRAM_EXTENSION = .extension Description' 438 439 If your post processor outputs files in all caps you might want to add 440 the following line: 441 442 * 'PROGRAM_EXTENSION = .NGC XYZ Post Processor' 443 444 The following lines add support for the image-to-G code converter 445 included with LinuxCNC. 446 447 * 'PROGRAM_EXTENSION = .png,.gif,.jpg Greyscale Depth Image' 448 ** 'png = image-to-gcode' 449 ** 'gif = image-to-gcode' 450 ** 'jpg = image-to-gcode' 451 452 An example of a custom G code converter located in the linuxcnc directory. 453 454 * 'PROGRAM_EXTENSION = .gcode 3D Printer 455 ** 'gcode = /home/mill/linuxcnc/convert.py' 456 457 NOTE: The program file assoiated with an extension must have either the full 458 path to the program or be located in a directory that is on the system path. 459 460 It is also possible to specify an interpreter: 461 462 * 'PROGRAM_EXTENSION = .py Python Script' 463 ** 'py = python' 464 465 In this way, any Python script can be opened, and its output is 466 treated as g-code. One such example script is available at 467 nc_files/holecircle.py. This script creates g-code for drilling a 468 series of holes along the circumference of a circle. Many more g-code 469 generators are on the LinuxCNC Wiki site 470 http://wiki.linuxcnc.org/[http://wiki.linuxcnc.org/]. 471 472 If the environment variable AXIS_PROGRESS_BAR is set, then lines 473 written to stderr of the form 474 475 * 'FILTER_PROGRESS=%d' 476 477 sets the AXIS progress bar to the given percentage. This feature 478 should be used by any filter that runs for a long time. 479 480 Python filters should use the print function to output the result to Axis. 481 482 This example program filters a file and adds a W axis to match the Z axis. 483 It depends on there being a space between each axis word to work. 484 485 ---- 486 #!/usr/bin/env python 487 488 import sys 489 490 def main(argv): 491 492 openfile = open(argv[0], 'r') 493 file_in = openfile.readlines() 494 openfile.close() 495 496 file_out = [] 497 for line in file_in: 498 # print line 499 if line.find('Z') != -1: 500 words = line.rstrip('\n') 501 words = words.split(' ') 502 newword = '' 503 for i in words: 504 if i[0] == 'Z': 505 newword = 'W'+ i[1:] 506 if len(newword) > 0: 507 words.append(newword) 508 newline = ' '.join(words) 509 file_out.append(newline) 510 else: 511 file_out.append(line) 512 for item in file_out: 513 print "%s" % item 514 515 if __name__ == "__main__": 516 main(sys.argv[1:]) 517 ---- 518 519 [[sec:rs274ngc-section]](((INI File, RS274NGC Section))) 520 521 === [RS274NGC] Section 522 523 * 'PARAMETER_FILE = myfile.var' - 524 (((PARAMETER FILE))) The file located in the same directory as the ini 525 file which contains the parameters used by the interpreter (saved 526 between runs). 527 528 * 'ORIENT_OFFSET = 0' - 529 (((ORIENT OFFSET))) A float value added to the R word parameter 530 of an <<mcode:m19,M19 Orient Spindle>> operation. Used to define an arbitrary 531 zero position regardless of encoder mount orientation. 532 533 * 'RS274NGC_STARTUP_CODE = G17 G20 G40 G49 G64 P0.001 G80 G90 G92 G94 G97 G98' - 534 (((RS274NGC STARTUP CODE))) A string of NC codes that the interpreter 535 is initialized with. This is not a substitute for specifying modal 536 g-codes at the top of each ngc file, because the modal codes of 537 machines differ, and may be changed by g-code interpreted earlier in 538 the session. 539 540 * 'SUBROUTINE_PATH = ncsubroutines:/tmp/testsubs:lathesubs:millsubs' - 541 (((SUBROUTINE PATH))) Specifies a colon (:) separated list of up to 10 542 directories to be searched when single-file subroutines are specified 543 in gcode. These directories are searched after searching 544 [DISPLAY]PROGRAM_PREFIX (if it is specified) and before searching 545 [WIZARD]WIZARD_ROOT (if specified). The paths are searched in the order 546 that they are listed. The first matching subroutine file 547 found in the search is used. Directories are specified relative to the 548 current directory for the ini file or as absolute paths. The list must 549 contain no intervening whitespace. 550 551 * 'CENTER_ARC_RADIUS_TOLERANCE_INCH = n' Default 0.00005 552 553 * 'CENTER_ARC_RADIUS_TOLERANCE_MM = n' Default 0.00127 554 555 * 'USER_M_PATH = myfuncs:/tmp/mcodes:experimentalmcodes' - (((USER M PATH))) 556 Specifies a list of colon (:) separated directories for user defined 557 functions. Directories are specified relative to the current directory 558 for the ini file or as absolute paths. The list must contain no intervening 559 whitespace. 560 + 561 A search is made for each possible user defined function, typically 562 (M100-M199). The search order is: 563 + 564 . [DISPLAY]PROGRAM_PREFIX (if specified) 565 . If [DISPLAY]PROGRAM_PREFIX is not specified, search the default location: nc_files 566 . Then search each directory in the list [RS274NGC]USER_M_PATH 567 + 568 The first executable M1xx found in the search is used for each M1xx. 569 570 [NOTE] 571 The maximum number of USER_M_PATH directories is defined at compile 572 time (typ: 'USER_DEFINED_FUNCTION_MAX_DIRS == 5'). 573 574 * 'FEATURES = 0' - An integer value representing the bitmask of optional 575 features to be enabled. These are typically non-backward-compatible and 576 experimental in nature. See 577 <<remap:ini-features,Optional Interpreter Features>> in the 578 <<cha:remap,Remap Extending G-Code>> chapter for details. 579 580 [NOTE] 581 [WIZARD]WIZARD_ROOT is a valid search path but the Wizard has not been fully 582 implemented and the results of using it are unpredictable. 583 584 * 'REMAP=M400 modalgroup=10 argspec=Pq ngc=myprocedure' 585 See <<cha:remap,Remap Extending G-Code>> chapter for details. 586 587 * 'ON_ABORT_COMMAND=O <on_abort> call' 588 See <<cha:remap,Remap Extending G-Code>> chapter for details. 589 590 [[sec:emcmot-section]](((INI File, EMCMOT Section))) 591 592 === [EMCMOT] Section 593 594 This section is a custom section and is not used by LinuxCNC directly. Most 595 configurations use values from this section to load the motion controller. For 596 more information on the motion controller see the <<sec:motion,Motion>> 597 Section. 598 599 * 'EMCMOT = motmod' - the motion controller name is typically used here. 600 601 * 'BASE_PERIOD = 50000' - the 'Base' task period in nanoseconds. 602 603 * 'SERVO_PERIOD = 1000000' - This is the "Servo" task period in nanoseconds. 604 605 * 'TRAJ_PERIOD = 100000' - This is the 'Trajectory Planner' task period in 606 nanoseconds. 607 608 * 'COMM_TIMEOUT = 1.0' - Number of seconds to wait for Motion (the 609 realtime part of the motion controller) to acknowledge receipt of 610 messages from Task (the non-realtime part of the motion controller). 611 612 [[sec:task-section]](((INI File, TASK Section))) 613 614 === [TASK] Section 615 616 * 'TASK = milltask' - 617 Specifies the name of the 'task' executable. The 'task' executable does various 618 things, such as communicate with the UIs over NML, communicate with the 619 realtime motion planner over non-HAL shared memory, and interpret gcode. 620 Currently there is only one task executable that makes sense for 621 99.9% of users, milltask. 622 623 * 'CYCLE_TIME = 0.010' - 624 The period, in seconds, at which TASK will run. This parameter 625 affects the polling interval when waiting for motion to complete, when 626 executing a pause instruction, and when accepting a command from a user 627 interface. There is usually no need to change this number. 628 629 [[sec:hal-section]](((INI File, HAL Section))) 630 631 === [HAL] section 632 633 * 'HALFILE = example.hal' - Execute the file 'example.hal' at start up. 634 If 'HALFILE' is specified multiple times, the files are executed in the order they 635 appear in the ini file. Almost all configurations will have at least 636 one 'HALFILE', and stepper systems typically have two such files, one which 637 specifies the generic stepper configuration ('core_stepper.hal') and 638 one which specifies the machine pin out ('xxx_pinout.hal'). 639 HALFILES are found using a search. If the named file is found in the directory 640 containing the ini file, it is used. If the named file is not found in this 641 ini file directory, a search is made using a system library of halfiles. 642 A HALFILE may also be specified as an absolute path (when the name starts with 643 a '/' character). Absolute paths are not recommended as their use may limit 644 relocation of configurations. 645 646 * 'HALFILE = texample.tcl [arg1 [arg2] ...]]' - Execute the tcl file 'texample.tcl' 647 at start up with arg1, arg2, etc as ::argv list. Files with a .tcl suffix are 648 processed as above but use haltcl for processing See the 649 <<cha:haltcl,HALTCL Chapter>> for more information. 650 651 * 'HALFILE = LIB:sys_example.hal' - Execute the system library file 'sys_example.hal' 652 at start up. 653 Explicit use of the LIB: prefix causes use of the system library HALFILE without 654 searching the ini file directory. 655 656 * 'HALFILE = LIB:sys_texample.tcl [arg1 [arg2 ...]]' - Execute the system library 657 file 'sys_texample.tcl' at start up. 658 Explicit use of the LIB: prefix causes use of the system library HALFILE without 659 searching the ini file directory. 660 + 661 HALFILE items specify files that loadrt Hal components and make signal 662 connections between component pins. Common mistakes are 1) omission of the 663 addf statement needed to add a component's function(s) to a thread, 2) 664 incomplete signal (net) specifiers. Omission of required addf statements is 665 almost always an error. Signals usually include one or more input 666 connections and a single output (but both are not strictly required). 667 A system library file is provided to make checks for these conditions and 668 report to stdout and in a popup gui: 669 ---- 670 HALFILE = LIB:halcheck.tcl [ nopopup ] 671 ---- 672 [NOTE] 673 The LIB:halcheck.tcl line should be the last [HAL]HALFILE. 674 Specify the 'nopopup' option to suppress the popup message and allow immediate starting. 675 Connections made using a POSTGUI_HALFILE are not checked. 676 677 678 * 'TWOPASS = ON' - Use twopass processing for loading HAL components. With TWOPASS processing, 679 [HAL]HALFILE= lines are processed in two passes. In the first pass (pass0), all 680 HALFILES are read and multiple appearances of loadrt and loadusr commands are accumulated. 681 These accumulated load commands are executed at the end of pass0. This accumulation allows 682 load lines to be specified more than once for a given component (provided the 683 names= names used are unique on each use). In the second pass (pass1), the 684 HALFILES are reread and all commands except the previously executed load commands 685 are executed. 686 687 * 'TWOPASS = nodelete verbose' - The TWOPASS feature can be activated with any 688 non-null string including the keywords verbose and nodelete. The verbose 689 keyword causes printing of details to stdout. The nodelete keyword preserves 690 temporary files in /tmp. 691 + 692 For more information see the <<cha:hal-twopass,Hal TWOPASS>> chapter. 693 694 * 'HALCMD = command' - Execute 'command' as a single HAL command. 695 If 'HALCMD' is specified multiple times, the commands are executed in the order 696 they appear in the ini file. 'HALCMD' lines are executed after all 697 'HALFILE' lines. 698 699 * 'SHUTDOWN = shutdown.hal' - Execute the file 'shutdown.hal' when LinuxCNC is exiting. 700 Depending on the hardware drivers used, this may make it possible to set outputs to 701 defined values when LinuxCNC is exited normally. However, because there is 702 no guarantee this file will be executed (for instance, in the case of a 703 computer crash) it is not a replacement for a proper physical e-stop 704 chain or other protections against software failure. 705 706 * 'POSTGUI_HALFILE = example2.hal' - Execute 'example2.hal' after the GUI has created 707 its HAL pins. Some GUIs create hal pins and support the use of a postgui halfile 708 to use them. GUIs that support postgui halfiles include Touchy, Axis, Gscreen, and 709 gmoccapy. 710 711 See section <<sec:pyvcp-with-axis,pyVCP with Axis>> Section for more information. 712 713 * 'HALUI = halui' - adds the HAL user interface pins. For more information see 714 the <<cha:hal-user-interface,HAL User Interface>> chapter. 715 716 [[sec:halui-section]](((INI File, HALUI Section))) 717 718 === [HALUI] section 719 720 * 'MDI_COMMAND = G53 G0 X0 Y0 Z0' - 721 An MDI command can be executed by using halui.mdi-command-00. Increment 722 the number for each command listed in the [HALUI] section. 723 724 [[sec:applications-section]](((INI File, APPLICATIONS Section))) 725 726 === [APPLICATIONS] Section 727 728 LinuxCNC can start other applications before the specified gui is started. 729 The applications can be started after a specified delay to allow for 730 gui-dependent actions (like creating gui-specific hal pins). 731 732 * 'DELAY = value' - seconds to wait beore starting other 733 applications. A delay may be needed if an application has 734 dependencies on [HAL]POSTGUI_HALFILE actions or gui-created 735 hal pins (default DELAY=0). 736 737 * 'APP = appname [arg1 [arg2 ...]]' - Application to be started. 738 This specification can be included multiple times. The appname can be 739 explicitly named as an absolute or tilde specified filename (first character 740 is / or ~), a relative filename (first characters of filename are ./), or as 741 a file in the inifile directory. If no executable file is found using 742 these names, then the user search PATH is used to find the application. 743 744 Examples: 745 746 ** Simulate inputs to hal pins for testing (using sim_pin -- a simple gui to set inputs to parameters, unconnected pins, or signals with no writers): 747 748 APP = sim_pin motion.probe-input halui.abort motion.analog-in-00 749 750 ** Invoke halshow with a previuosly saved watchlist. Since linuxcnc sets the working directory to the directory for the inifile, you can refer to files in that directory (example: my.halshow): 751 752 APP = halshow my.halshow 753 754 ** Alternatively, a watchlist file identified with a full pathname could be specified: 755 756 APP = halshow ~/saved_shows/spindle.halshow 757 758 ** Open halscope using a previously saved configuration: 759 760 APP = halscope -i my.halscope 761 762 [[sec:traj-section]](((INI File, TRAJ Section))) 763 764 === [TRAJ] Section 765 766 [WARNING] 767 The new Trajectory Planner (TP) is on by default. + 768 If you have no TP settings in your [TRAJ] section - LinuxCNC defaults to: + 769 ARC_BLEND_ENABLE = 1 + 770 ARC_BLEND_FALLBACK_ENABLE = 0 + 771 ARC_BLEND_OPTIMIZATION_DEPTH = 50 + 772 ARC_BLEND_GAP_CYCLES = 4 + 773 ARC_BLEND_RAMP_FREQ = 100 774 775 The [TRAJ] section contains general parameters for the trajectory 776 planning module in 'motion'. 777 778 * 'ARC_BLEND_ENABLE = 1' - Turn on new TP. If set to 0 TP uses parabolic 779 blending (1 segment look ahead.) Default value 1. 780 781 * 'ARC_BLEND_FALLBACK_ENABLE = 0' - Optionally fall back to parabolic blends 782 if the estimated speed is faster. However, this estimate is rough, and it 783 seems that just disabling it gives better performance. Default value 0. 784 785 * 'ARC_BLEND_OPTIMIZATION_DEPTH = 50' - Look ahead depth in number of segments. 786 + 787 To expand on this a bit, you can choose this value somewhat arbitrarily. 788 Here's a formula to estimate how much 'depth' you need for a particular 789 config: 790 + 791 # n = v_max / (2.0 * a_max * t_c) 792 # where: 793 # n = optimization depth 794 # v_max = max axis velocity (UU / sec) 795 # a_max = max axis acceleration (UU / sec) 796 # t_c = servo period (seconds) 797 + 798 So, a machine with a maximum axis velocity of 10 IPS, a max acceleration 799 of 100 IPS^2, and a servo period of 0.001 sec would need: 800 + 801 10 / (2.0 * 100 * 0.001) = 50 segments to always reach maximum velocity 802 along the fastest axis. 803 + 804 In practice, this number isn't that important to tune, since the 805 look ahead rarely needs the full depth unless you have lots of very short 806 segments. If during testing, you notice strange slowdowns and can't 807 figure out where they come from, first try increasing this depth using 808 the formula above. 809 + 810 If you still see strange slowdowns, it may be because you have short 811 segments in the program. If this is the case, try adding a small 812 tolerance for Naive CAM detection. A good rule of thumb is this: 813 + 814 # min_length ~= v_req * t_c 815 # where: 816 # v_req = desired velocity in UU / sec 817 # t_c = servo period (seconds) 818 + 819 If you want to travel along a path at 1 IPS = 60 IPM, and your servo 820 period is 0.001 sec, then any segments shorter than min_length will slow 821 the path down. If you set Naive CAM tolerance to around this min length, 822 overly short segments will be combined together to eliminate this 823 bottleneck. Of course, setting the tolerance too high means big path 824 deviations, so you have to play with it a bit to find a good value. I'd 825 start at 1/2 of the min_length, then work up as needed. 826 827 * 'ARC_BLEND_GAP_CYCLES = 4' How short the previous segment must be before 828 the trajectory planner 'consumes' it. 829 + 830 Often, a circular arc blend will leave short line segments in between 831 the blends. Since the geometry has to be circular, we can't blend over 832 all of a line if the next one is a little shorter. Since the trajectory 833 planner has to touch each segment at least once, it means that very tiny 834 segments will slow things down significantly. My fix to this way to 835 "consume" the short segment by making it a part of the blend arc. Since 836 the line+blend is one segment, we don't have to slow down to hit the 837 very short segment. Likely, you won't need to touch this setting. 838 839 * 'ARC_BLEND_RAMP_FREQ = 20' - This is a 'cutoff' frequency for using ramped 840 velocity. 841 + 842 'Ramped velocity' in this case just means constant acceleration over the 843 whole segment. This is less optimal than a trapezoidal velocity profile, 844 since the acceleration is not maximized. However, if the segment is 845 short enough, there isn't enough time to accelerate much before we hit 846 the next segment. Recall the short line segments from the previous 847 example. Since they're lines, there's no cornering acceleration, so 848 we're free to accelerate up to the requested speed. However, if this 849 line is between two arcs, then it will have to quickly decelerate again 850 to be within the maximum speed of the next segment. This means that we 851 have a spike of acceleration, then a spike of deceleration, causing a 852 large jerk, for very little performance gain. This setting is a way to 853 eliminate this jerk for short segments. 854 + 855 Basically, if a segment will complete in less time than 1 / 856 ARC_BLEND_RAMP_FREQ, we don't bother with a trapezoidal velocity profile 857 on that segment, and use constant acceleration. (Setting 858 ARC_BLEND_RAMP_FREQ = 1000 is equivalent to always using trapezoidal 859 acceleration, if the servo loop is 1kHz). 860 + 861 You can characterize the worst-case loss of performance by comparing the 862 velocity that a trapezoidal profile reaches vs. the ramp: 863 + 864 # v_ripple = a_max / (4.0 * f) 865 # where: 866 # v_ripple = average velocity "loss" due to ramping 867 # a_max = max axis acceleration 868 # f = cutoff frequency from INI 869 + 870 For the aforementioned machine, the ripple for a 20Hz cutoff frequency 871 is 100 / (4 * 20) = 1.25 IPS. This seems high, but keep in mind that it 872 is only a worst-case estimate. In reality , the trapezoidal motion 873 profile is limited by other factors, such as normal acceleration or 874 requested velocity, and so the actual performance loss should be much 875 smaller. Increasing the cutoff frequency can squeeze out more 876 performance, but make the motion rougher due to acceleration 877 discontinuities. A value in the range 20Hz to 200Hz should be reasonable 878 to start. 879 + 880 Finally, no amount of tweaking will speed up a toolpath with lots of 881 small, tight corners, since you're limited by cornering acceleration. 882 883 * 'SPINDLES = 3' - The number of spindles to support. It is imperative that this 884 number matches the "num_spindles" parameter passed to the motion module. 885 886 * 'COORDINATES = X Y Z' - The names of the axes being controlled. 887 Only X, Y, Z, A, B, C, U, V, W are valid. Only axes named in 'COORDINATES' 888 are accepted in g-code. It is permitted to write an axis name twice 889 (e.g., X Y Y Z for a gantry machine). 890 For the common 'trivkins kinematics', joint numbers are assigned in sequence 891 according to the trivkins parameter 'coordinates='. So, for trivkins 892 'coordinates=xz', joint0 corresponds to X and joint1 corresponds to Z. 893 See the kinematics man page ('$ man kins') for information on 894 trivkins and other kinematics modules. 895 896 * 'LINEAR_UNITS = <units>' - (((LINEAR UNITS))) Specifies the 'machine units' for linear axes. 897 Possible choices are mm or inch. 898 This does not affect the linear units in NC code (the G20 and G21 899 words do this). 900 901 * 'ANGULAR_UNITS = <units>' - (((ANGULAR UNITS))) Specifies the 'machine units' for rotational axes. 902 Possible choices are 'deg', 'degree' (360 per circle), 'rad', 'radian' 903 (2pi per circle), 'grad', or 'gon' (400 per circle). 904 This does not affect the angular units of NC code. In RS274NGC, A-, B- 905 and C- words are always expressed in degrees. 906 907 * 'DEFAULT_LINEAR_VELOCITY = 0.0167' - The initial rate for jogs of linear axes, in 908 machine units per second. The value shown in 'Axis' equals 909 machine units per minute. 910 911 * 'DEFAULT_LINEAR_ACCELERATION = 2.0' - In machines with nontrivial kinematics, the acceleration used 912 for "teleop" (Cartesian space) jogs, in 'machine units' per second per second. 913 914 * 'MAX_LINEAR_VELOCITY = 5.0' - (((MAX VELOCITY))) The maximum velocity for any axis or coordinated 915 move, in 'machine units' per second. The value shown equals 300 units per 916 minute. 917 918 * 'MAX_LINEAR_ACCELERATION = 20.0' - (((MAX ACCELERATION))) The maximum acceleration for any axis or 919 coordinated axis move, in 'machine units' per second per second. 920 921 * 'POSITION_FILE = position.txt' - If set to a non-empty value, the joint positions are stored between 922 runs in this file. This allows the machine to start with the same 923 coordinates it had on shutdown. This assumes there was no movement of 924 the machine while powered off. If unset, joint positions are not stored 925 and will begin at 0 each time LinuxCNC is started. This can help on smaller 926 machines without home switches. If using the Mesa resolver interface 927 this file can be used to emulate absolute encoders and eliminate the 928 need for homing (with no loss of accuracy). See the hostmot2 manpage 929 for more details. 930 931 * 'NO_FORCE_HOMING = 1' - The default behavior is for LinuxCNC to force the 932 user to home the machine before any MDI command or a program is run. 933 Normally, only jogging is allowed before homing. For configurations using 934 identity kinematics, setting NO_FORCE_HOMING = 1 allows the user to make 935 MDI moves and run programs without homing the machine first. Interfaces 936 using identity kinematics without homing ability will need to have this 937 option set to 1. 938 939 * 'HOME = 0 0 0 0 0 0 0 0 0' - World home position needed for kinematics modules 940 that compute world coordinates using kinematicsForward() when switching 941 from joint to teleop mode. Up to nine coordinate values (X Y Z A B C U V W) 942 may be specified, unused trailing items may be omitted. This value is only 943 used for machines with nontrivial kinematics. On machines with trivial 944 kinematics (mill, lathe, gantry types) this value is ignored. 945 Note: the sim hexapod config requires a non-zero value for the Z coordinate. 946 947 [WARNING] 948 LinuxCNC will not know your joint travel limits when using 'NO_FORCE_HOMING = 1'. 949 950 [[sec:kins-section]](((INI File, KINS Section))) 951 952 === [KINS] Section 953 * 'JOINTS = 3' - Specifies the number of joints (motors) in the system. 954 For example, a trivkins XYZ machine with a single motor for each axis has 3 955 joints. A gantry machine with one motor on each of two of the axes, 956 and two motors on the third axis, has 4 joints. 957 (This config variable may be used by a gui to set the number of joints 958 (num_joints) specified to the motion module (motmod)). 959 The Axis gui, pncconf, and stepconf use this item. 960 961 * 'KINEMATICS = trivkins' - Specify a kinematics module for the motion module. 962 Guis may use this variable to specify the loadrt line in hal files for 963 the motmod module. For more information on kinematics modules see the 964 manpage: '$ man kins' 965 966 [[sec:axis-section]](((INI File, AXIS Section))) 967 968 === [AXIS_<letter>] Section 969 The <letter> specifies one of: X Y Z A B C U V W 970 971 * 'MAX_VELOCITY = 1.2' - 972 Maximum velocity for this axis in <<sec:traj-section,machine units>> per second. 973 974 * 'MAX_ACCELERATION = 20.0' - 975 Maximum acceleration for this axis in machine units per 976 second squared. 977 978 * 'MIN_LIMIT = -1000' - 979 (((MIN LIMIT))) The minimum limit (soft limit) for axis motion, in machine units. 980 When this limit is exceeded, the controller aborts axis motion. 981 982 * 'MAX_LIMIT = 1000' - 983 (((MAX LIMIT))) The maximum limit (soft limit) for axis motion, in machine units. 984 When this limit is exceeded, the controller aborts axis motion. 985 986 * 'WRAPPED_ROTARY = 1' - 987 When this is set to 1 for an ANGULAR joint the joint will move 0-359.999 988 degrees. Positive Numbers will move the joint in a positive direction and 989 negative numbers will move the joint in the negative direction. 990 991 * 'LOCKING_INDEXER_JOINT = 4' - This value selects a joint to use for 992 a locking indexer for the specified axis <letter>. In this example, the 993 joint is 4 which would correspond to the B axis for a XYZAB system with 994 trivkins (identity) kinematics. 995 When set, a G0 move for this axis will initiate an unlock with the 996 joint.4.unlock pin then wait for the joint.4.is-unlocked pin then move 997 the joint at the rapid rate for that joint. After the move the 998 joint.4.unlock will be false and motion will wait for joint.4.is-unlocked 999 to go false. Moving with other joints is not allowed when moving a 1000 locked rotary joint. 1001 To create the unlock pins, use the motmod parameter: 1002 1003 unlock_joints_mask=jointmask 1004 1005 The jointmask bits are: (LSB)0:joint0, 1:joint1, 2:joint2, ... 1006 1007 Example: loadrt motmod ... unlock_joints_mask=0x38 1008 creates unlock pins for joints 3,4,5 1009 1010 * 'OFFSET_AV_RATIO = 0.1' - If nonzero, this item enables the use of 1011 hal input pins for external axis offsets: 1012 1013 'axis.<letter>.eoffset-enable' 1014 'axis.<letter>.eoffset-counts' 1015 'axis.<letter>.eoffset-scale' 1016 1017 See the chapter: <<cha:external-offsets, 'External Axis Offsets'>> for 1018 usage information. 1019 1020 [[sec:joint-section]](((INI File, JOINT Section))) 1021 1022 === [JOINT_<num>] Section 1023 The <num> specifies the joint number 0 ... (num_joints-1) 1024 The value of 'num_joints' is set by [KINS]JOINTS= 1025 1026 The [JOINT_0], [JOINT_1], etc. sections contains general parameters for 1027 the individual components in the joint control module. The joint section 1028 names begin numbering at 0, and run through the number of joints 1029 specified in the [KINS]JOINTS entry minus 1. 1030 1031 Typically (for systems using 'trivkins kinematics', there is a 1:1 1032 correspondence between a joint and an axis): 1033 1034 * JOINT_0 = X 1035 * JOINT_1 = Y 1036 * JOINT_2 = Z 1037 * JOINT_3 = A 1038 * JOINT_4 = B 1039 * JOINT_5 = C 1040 * JOINT_6 = U 1041 * JOINT_7 = V 1042 * JOINT_8 = W 1043 1044 Other kinematics modules with identity kinematics are available to support 1045 configurations with partial sets of axes. For example, using trivkins 1046 with coordinates=XZ, the joint-axes relationships are: 1047 1048 * JOINT_0 = X 1049 * JOINT_1 = Z 1050 1051 For more information on kinematics modules see the manpage: '$ man kins' 1052 1053 * 'TYPE = LINEAR' - 1054 The type of joint, either LINEAR or ANGULAR. 1055 1056 * 'UNITS = INCH' - 1057 (((UNITS))) If specified, this setting overrides the related [TRAJ] UNITS setting. 1058 (e.g., [TRAJ]LINEAR_UNITS if the TYPE of this joint is LINEAR, 1059 [TRAJ]ANGULAR_UNITS if the TYPE of this joint is ANGULAR) 1060 1061 * 'MAX_VELOCITY = 1.2' - 1062 Maximum velocity for this joint in <<sec:traj-section,machine units>> per second. 1063 1064 * 'MAX_ACCELERATION = 20.0' - 1065 Maximum acceleration for this joint in machine units per 1066 second squared. 1067 1068 * 'BACKLASH = 0.0000' - 1069 (((Backlash))) Backlash in machine units. Backlash compensation value 1070 can be used to make up for small deficiencies in the hardware used to 1071 drive an joint. If backlash is added to an joint and you are using 1072 steppers the STEPGEN_MAXACCEL must be increased to 1.5 to 2 times the 1073 MAX_ACCELERATION for the joint. Excessive backlash compensation can cause an 1074 axis to jerk as it changes direction. If a COMP_FILE is specificed for an 1075 axis BACKLASH is not used. 1076 1077 // add a link to machine units 1078 1079 * 'COMP_FILE = file.extension' - 1080 (((Compensation))) The compensation file consists of map of position 1081 information for the joint. Compensation file values are in machine units. 1082 Each set of values are are on one line separated by a space. The first value 1083 is the nominal value (the commanded position). The second and third values 1084 depend on the setting of COMP_FILE_TYPE. Points in between nominal values 1085 are interpolated between the two nominals. Compensation files must start 1086 with the smallest nominal and be in ascending order to the largest value of 1087 nominals. File names are case sensitive and can contain letters and/or 1088 numbers. Currently the limit inside LinuxCNC is for 256 triplets per axis. 1089 + 1090 + 1091 If COMP_FILE is specified for an axis, BACKLASH is not used. A 1092 'COMP_FILE_TYPE' must be specified for each 'COMP_FILE'. 1093 1094 * 'COMP_FILE_TYPE = 0 or 1' - Specifies the type of compensation file. The 1095 first value is the nominal (commanded) position for both types. 1096 1097 ** 'Type 0:' The second value specifies the actual position as the axis is moving 1098 in the positive direction (increasing value) and the third value specifies 1099 the actual position as the axis is moving in the negative direction 1100 (decreasing value). 1101 + 1102 + 1103 Type 0 Example 1104 + 1105 ---- 1106 -1.000 -1.005 -0.995 1107 0.000 0.002 -0.003 1108 1.000 1.003 0.998 1109 ---- 1110 1111 ** 'Type 1:' The second value specifies positive offset from nominal while 1112 traveling in the positive direction. The third value specifies the negitive 1113 offset from nominal while traveling in a negitive direction. 1114 + 1115 + 1116 Type 1 Example 1117 + 1118 ---- 1119 -1.000 0.005 -0.005 1120 0.000 0.002 -0.003 1121 1.000 0.003 -0.004 1122 ---- 1123 1124 * 'MIN_LIMIT = -1000' - (((MIN LIMIT))) The minimum limit for axis motion, in 1125 machine units. When this limit is reached, the controller aborts axis 1126 motion. The axis must be homed before MIN_LIMIT is in force. For a rotary 1127 axis with unlimited rotation having no MIN_LIMIT for that axis in the 1128 [JOINT_n] section then the value -1e99 is used. 1129 1130 * 'MAX_LIMIT = 1000' - (((MAX LIMIT))) The maximum limit for axis motion, in 1131 machine units. When this limit is reached, the controller aborts axis 1132 motion. The axis must be homed before MAX_LIMIT is in force. For a rotary 1133 axis with unlimited rotation having no MAX_LIMIT for that axis in the 1134 [JOINT_n] section then the value 1e99 is used. 1135 1136 * 'MIN_FERROR = 0.010' - (((MIN FERROR))) This is the value in machine units by 1137 which the axis is permitted to deviate from commanded position at very low 1138 speeds. If MIN_FERROR is smaller than FERROR, the two produce a ramp of 1139 error trip points. You could think of this as a graph where one dimension is 1140 speed and the other is permitted following error. As speed increases the 1141 amount of following error also increases toward the FERROR value. 1142 1143 * 'FERROR = 1.0' - (((FERROR))) FERROR is the maximum allowable following error, 1144 in machine units. If the difference between commanded and sensed position 1145 exceeds this amount, the controller disables servo calculations, sets all 1146 the outputs to 0.0, and disables the amplifiers. If MIN_FERROR is present in 1147 the .ini file, velocity-proportional following errors are used. Here, the 1148 maximum allowable following error is proportional to the speed, with FERROR 1149 applying to the rapid rate set by [TRAJ]MAX_VELOCITY, and proportionally 1150 smaller following errors for slower speeds. The maximum allowable following 1151 error will always be greater than MIN_FERROR. This prevents small following 1152 errors for stationary axes from inadvertently aborting motion. Small 1153 following errors will always be present due to vibration, etc. 1154 1155 * 'LOCKING_INDEXER = 1' - 1156 Indicates the joint is used as a locking indexer. 1157 1158 .Homing 1159 1160 These parameters are Homing related, for a better explanation read the 1161 <<cha:homing-configuration,Homing Configuration>> Chapter. 1162 1163 * 'HOME = 0.0' - 1164 The position that the joint will go to upon completion of the homing 1165 sequence. 1166 1167 * 'HOME_OFFSET = 0.0' - 1168 The joint position of the home switch or index pulse, in 1169 <<sec:traj-section,machine units>>. When the home point is found during 1170 the homing process, this is the position that is assigned to that point. 1171 When sharing home and limit switches and using a home sequence that will 1172 leave the home/limit switch in the toggled state the home offset can be 1173 used define the home switch position to be other than 0 if your HOME 1174 position is desired to be 0. 1175 1176 * 'HOME_SEARCH_VEL = 0.0' - 1177 (((HOME SEARCH VEL))) Initial homing velocity in machine units per second. 1178 Sign denotes direction of travel. A value of zero means assume that the current 1179 location is the home position for the machine. If your machine has no 1180 home switches you will want to leave this value at zero. 1181 1182 * 'HOME_LATCH_VEL = 0.0' - 1183 Homing velocity in machine units per second to the home 1184 switch latch position. Sign denotes direction of travel. 1185 1186 * 'HOME_FINAL_VEL = 0.0' - 1187 Velocity in machine units per second from home latch position to home 1188 position. If left at 0 or not included in the joint rapid velocity is 1189 used. Must be a positive number. 1190 1191 * 'HOME_USE_INDEX = NO' - 1192 If the encoder used for this joint has an index pulse, and the motion 1193 card has provision for this signal you may set it to yes. When it is 1194 yes, it will affect the kind of home pattern used. Currently, you can't 1195 home to index with steppers unless you're using stepgen in velocity mode 1196 and PID. 1197 1198 * 'HOME_INDEX_NO_ENCODER_RESET = NO' - 1199 Use YES if the encoder used for this joint does not reset its counter 1200 when an index pulse is detected after assertion of the joint 1201 index_enable hal pin. Applicable only for HOME_USE_INDEX = YES. 1202 1203 * 'HOME_IGNORE_LIMITS = NO' - 1204 When you use the limit switch as a home switch and the limit switch 1205 this should be set to YES. When set to YES the limit switch for this 1206 joint is ignored when homing. You must configure your homing 1207 so that at the end of your home move the home/limit switch is not in the 1208 toggled state you will get a limit switch error after the home move. 1209 1210 * 'HOME_IS_SHARED = <n>' - 1211 If the home input is shared by more than one joint set <n> to 1 to 1212 prevent homing from starting if the one of the shared switches is 1213 already closed. Set <n> to 0 to permit homing if a switch is closed. 1214 1215 * 'HOME_ABSOLUTE_ENCODER = 0 | 1 | 2' - 1216 Used to indicate the joint uses an absolute encoder. At a request 1217 for homing, the current joint value is set to the 'HOME_OFFSET' value. 1218 If the 'HOME_ABSOLUTE_ENCODER' setting is 1, the machine makes the usual 1219 final move to the 'HOME' value. 1220 If the 'HOME_ABSOLUTE_ENCODER' setting is 2, no final move is made. 1221 1222 * 'HOME_SEQUENCE = <n>' - 1223 Used to define the "Home All" sequence. <n> must start at 0 or 1224 1 or -1. Additional sequences may be specified with numbers increasing 1225 by 1 (in absolute value). Skipping of sequence numbers is not allowed. 1226 If a HOME_SEQUENCE is omitted, the joint will not be homed by the 1227 "Home All" function. More than one joint can be homed at the same 1228 time by specifying the same sequence number for more than one joint. 1229 A negative sequence number is used to defer the final move for 1230 all joints having that (negative or positive) sequence number. 1231 For additional info, see: <<sec:homing-section,HOME SEQUENCE>> 1232 1233 * 'VOLATILE_HOME = 0' - 1234 When enabled (set to 1) this joint will be unhomed if the Machine 1235 Power is off or if E-Stop is on. This is useful if your machine has 1236 home switches and does not have position feedback such as a step and 1237 direction driven machine. 1238 1239 .Servo 1240 1241 These parameters are relevant to joints controlled by servos. 1242 1243 [WARNING] 1244 The following are custom INI file entries that you may find in a sample INI file 1245 or a wizard generated file. These are not used by the LinuxCNC software. They 1246 are only there to put all the settings in one place. For more information on 1247 custom INI file entries see the 1248 <<sub:custom-variables,Custom Sections and Variables>> subsection. 1249 1250 The following items might be used by a PID component and the assumption is 1251 that the output is volts. 1252 1253 * 'DEADBAND = 0.000015' - How close is close enough to consider the motor in position, 1254 in <<sec:traj-section,machine units>>. This is often set to a distance equivalent to 1, 1.5, 2, 1255 or 3 encoder counts, but there are no strict rules. 1256 Looser (larger) settings allow less servo 'hunting' at the expense of lower accuracy. 1257 Tighter (smaller) settings attempt higher accuracy at the expense of more servo 'hunting'. 1258 Is it really more accurate if it's also more uncertain? 1259 As a general rule, it's good to avoid, or at least limit, servo 'hunting' if you can. 1260 1261 Be careful about going below 1 encoder count, since you may create a condition where 1262 there is no place that your servo is happy. This can go beyond 'hunting' (slow) to 1263 'nervous' (rapid), and even to 'squealing' which is easy to confuse with 1264 oscillation caused by improper tuning. Better to be a count or two loose 1265 here at first, until you've been through 'gross tuning' at least. 1266 1267 Example of calculating machine units per encoder pulse to use in deciding DEADBAND value: 1268 1269 /////////////////////////////////////////////////////////// 1270 latexmath:[ \frac{X\, inches}{1\, encoder\, count} = 1271 \frac{1\, revolution}{1000\, encoder\, lines} \times 1272 \frac{1\, encoder\, line}{4\, quadrature\, counts} \times 1273 \frac{0.200\, inches}{1\, revolution} = 1274 \frac{0.200\, inches}{4000\, encoder\, counts} = 1275 \frac{0.000050\, inches}{1\, encoder\, count} ] 1276 /////////////////////////////////////////////////////////// 1277 1278 image::images/encoder-counts-math.png[align="center"] 1279 1280 * 'BIAS = 0.000' - This is used by hm2-servo and some others. 1281 Bias is a constant amount 1282 that is added to the output. In most cases it should be left at zero. 1283 However, it can sometimes be useful to compensate for offsets in servo 1284 amplifiers, or to balance the weight of an object that moves 1285 vertically. bias is turned off when the PID loop is disabled, just like 1286 all other components of the output. 1287 1288 * 'P = 50' - The proportional gain for the joint servo. This value 1289 multiplies the 1290 error between commanded and actual position in machine units, resulting 1291 in a contribution to the computed voltage for the motor amplifier. The 1292 units on the P gain are volts per machine unit, e.g., 1293 image:images/p-term.png[height=25] 1294 1295 //latexmath:[$\frac{volt}{mu}$]. 1296 1297 * 'I = 0' - The integral gain for the joint servo. The value 1298 multiplies the 1299 cumulative error between commanded and actual position in machine 1300 units, resulting in a contribution to the computed voltage for the 1301 motor amplifier. The units on the I gain are volts per machine unit 1302 second, e.g., image:images/i-term.png[height=25] 1303 1304 //latexmath:[$\frac{volt}{mu\, s}$]. 1305 1306 * 'D = 0' - The derivative gain for the joint servo. The value 1307 multiplies the 1308 difference between the current and previous errors, resulting in a 1309 contribution to the computed voltage for the motor amplifier. The units 1310 on the D gain are volts per machine unit per second, e.g., 1311 image:images/i-term.png[height=25] 1312 1313 // latexmath:[$\frac{volt}{mu/s}$]. 1314 1315 * 'FF0 = 0' - The 0th order feed forward gain. This number is 1316 multiplied by the 1317 commanded position, resulting in a contribution to the computed voltage 1318 for the motor amplifier. The units on the FF0 gain are volts per 1319 machine unit, e.g., image:images/p-term.png[height=25] 1320 1321 // latexmath:[$\frac{volt}{mu}$]. 1322 1323 * 'FF1 = 0' - The 1st order feed forward gain. This number is 1324 multiplied by the 1325 change in commanded position per second, resulting in a contribution to 1326 the computed voltage for the motor amplifier. The units on the FF1 gain 1327 are volts per machine unit per second, e.g., image:images/i-term.png[height=25] 1328 1329 // latexmath:[$\frac{volt}{mu\, s}$]. 1330 1331 * 'FF2 = 0' - The 2nd order feed forward gain. This number is 1332 multiplied by the 1333 change in commanded position per second per second, resulting in a 1334 contribution to the computed voltage for the motor amplifier. The units 1335 on the FF2 gain are volts per machine unit per second per second, 1336 e.g., image:images/ff2.png[height=25] 1337 1338 // latexmath:[$\frac{volt}{mu\, s^{2}}$]. 1339 1340 * 'OUTPUT_SCALE = 1.000' - 1341 1342 * 'OUTPUT_OFFSET = 0.000' - These two values are the scale and offset factors for 1343 the joint output to the motor amplifiers. 1344 The second value (offset) is subtracted from 1345 the computed output (in volts), and divided by the first value (scale 1346 factor), before being written to the D/A converters. The units on the 1347 scale value are in true volts per DAC output volts. The units on the 1348 offset value are in volts. These can be used to linearize a DAC. 1349 Specifically, when writing outputs, the LinuxCNC first converts the desired 1350 output in quasi-SI units to raw actuator values, e.g., volts for an 1351 amplifier DAC. This scaling 1352 looks like: image:images/output-offset.png[] 1353 1354 // latexmath:[raw=\frac{output-offset}{scale}] 1355 1356 The value for scale can be obtained analytically by doing a unit 1357 analysis, i.e., units are [output SI units]/[actuator units]. For 1358 example, on a machine with a velocity mode amplifier such that 1359 1 volt results in 250 mm/sec velocity. 1360 1361 image::images/scale-math.png[align="center"] 1362 1363 // latexmath:[$ amplifier [volts] = (output [\frac{mm}{sec}] 1364 // - offset [\frac{mm}{sec}]) / 250 \frac{mm}{sec\, volt} ] $] 1365 1366 Note that the units of the offset are in machine units, e.g., 1367 mm/sec, and they are pre-subtracted from the sensor readings. The value 1368 for this offset is obtained by finding the value of your output which 1369 yields 0.0 for the actuator output. If the DAC is linearized, this 1370 offset is normally 0.0. 1371 1372 The scale and offset can be used to linearize the DAC as well, 1373 resulting in values that reflect the combined effects of amplifier 1374 gain, DAC non-linearity, DAC units, etc. 1375 1376 To do this, follow this procedure. 1377 1378 . Build a calibration table for the output, driving the DAC with a 1379 desired voltage and measuring the result. 1380 1381 . Do a least-squares linear fit to get coefficients a, b such 1382 that image:images/calibration-1.png[] 1383 . Note that we want raw output such that our measured result is 1384 identical to the commanded output. This means 1385 .. image:images/calibration-2.png[] 1386 .. image:images/calibration-3.png[] 1387 . As a result, the a and b coefficients from the linear fit can be 1388 used as the scale and offset for the controller directly. 1389 1390 See the following table for an example of voltage measurements. 1391 1392 // latexmath:[ meas=a*raw+b ] 1393 // latexmath:[ cmd=a*raw+b ] 1394 // latexmath:[ raw=(cmd-b)/a ] 1395 1396 .Output Voltage Measurements 1397 1398 [width="50%", cols="2*^", options="header"] 1399 |=============== 1400 |Raw | Measured 1401 |-10 | -9.93 1402 |-9 | -8.83 1403 |0 | -0.03 1404 |1 | 0.96 1405 |9 | 9.87 1406 |10 | 10.87 1407 |=============== 1408 1409 * 'MAX_OUTPUT = 10' - The maximum value for the output of the PID compensation 1410 that is written to the motor amplifier, in volts. The computed 1411 output value is clamped to this limit. The limit is applied before 1412 scaling to raw output units. The value is applied symmetrically to 1413 both the plus and the minus side. 1414 1415 * 'INPUT_SCALE = 20000' - in Sample configs 1416 * 'ENCODER_SCALE = 20000' - in PNCconf built configs 1417 Specifies the number of pulses that 1418 corresponds to a move of one machine unit as set in the [TRAJ] section. 1419 For a linear joint one machine unit will be equal to 1420 the setting of LINEAR_UNITS. 1421 For an angular joint one unit is equal to the setting in ANGULAR_UNITS. 1422 A second number, if specified, is ignored. 1423 For example, on a 2000 counts per rev encoder, and 10 1424 revs/inch gearing, and desired units of inch, we 1425 have: 1426 1427 image::images/encoder-scale.png[align="center"] 1428 1429 //latexmath:[ INPUT\_SCALE = 1430 //\frac{2000\, counts}{rev} \times \frac{10\, rev}{inch} = 1431 //\frac{20000\, counts}{inch} ] 1432 1433 .Stepper 1434 1435 These parameters are relevant to joints controlled by steppers. 1436 1437 [WARNING] 1438 The following are custom INI file entries that you may find in a sample INI file 1439 or a wizard generated file. These are not used by the LinuxCNC software. They 1440 are only there to put all the settings in one place. For more information on 1441 custom INI file entries see the 1442 <<sub:custom-variables,Custom Sections and Variables>> subsection. 1443 1444 The following items might be used by a stepgen component. 1445 1446 * 'SCALE = 4000' - in Sample configs 1447 * 'STEP_SCALE = 4000' - in PNCconf built configs 1448 Specifies the number of pulses that corresponds to a 1449 move of one machine unit as set in the [TRAJ] section. 1450 For stepper systems, this is 1451 the number of step pulses issued per machine unit. For a linear joint 1452 one machine unit will be equal to the setting of LINEAR_UNITS. For an 1453 angular joint one unit is equal to the setting in ANGULAR_UNITS. For 1454 servo systems, this is the number of feedback pulses per machine unit. 1455 A second number, if specified, is ignored. 1456 1457 For example, on a 1.8 degree stepper motor with half-stepping, and 10 1458 revs/inch gearing, and desired <<sec:traj-section,machine units>> of inch, we 1459 have: 1460 1461 image::images/stepper-scale.png[align="center"] 1462 1463 //latexmath:[ scale = 1464 //\frac{2\, steps}{1.8\, degree} \times \frac{360\, degree}{rev} \times \frac{10\, rev}{inch} = 1465 //\frac{4000\, steps}{inch} ] 1466 1467 * 'ENCODER_SCALE = 20000' (Optionally used in PNCconf built configs) - 1468 Specifies the number of pulses that 1469 corresponds to a move of one machine unit as set in the [TRAJ] section. 1470 For a linear joint one machine unit will be equal to 1471 the setting of LINEAR_UNITS. 1472 For an angular joint one unit is equal to the setting in ANGULAR_UNITS. 1473 A second number, if specified, is ignored. 1474 For example, on a 2000 counts per rev encoder, and 10 1475 revs/inch gearing, and desired units of inch, we 1476 have: 1477 1478 image::images/encoder-scale.png[align="center"] 1479 1480 //latexmath:[ ENCODER\_SCALE = 1481 //\frac{2000\, counts}{rev} \times \frac{10\, rev}{inch} = 1482 //\frac{20000\, counts}{inch} ] 1483 1484 1485 * 'STEPGEN_MAXACCEL = 21.0' - Acceleration limit for the step generator. 1486 This should be 1% to 10% 1487 larger than the joint MAX_ACCELERATION. This value improves the tuning 1488 of stepgen's "position loop". If you have added backlash compensation 1489 to an joint then this should be 1.5 to 2 times greater than 1490 MAX_ACCELERATION. 1491 1492 * 'STEPGEN_MAXVEL = 1.4' - Older configuration files have a velocity limit for 1493 the step 1494 generator as well. If specified, it should also be 1% to 10% larger 1495 than the joint MAX_VELOCITY. Subsequent testing has shown that use of 1496 STEPGEN_MAXVEL does not improve the tuning of stepgen's position loop. 1497 1498 1499 [[sec:emcio-section]](((INI File, EMCIO Section))) 1500 1501 === [EMCIO] Section 1502 1503 * 'EMCIO = io' - Name of IO controller program 1504 1505 * 'CYCLE_TIME = 0.100' - 1506 The period, in seconds, at which EMCIO will run. Making 1507 it 0.0 or a 1508 negative number will tell EMCIO not to sleep at all. There is usually 1509 no need to change this number. 1510 1511 * 'TOOL_TABLE = tool.tbl' - 1512 The file which contains tool information, described in 1513 the User Manual. 1514 1515 * 'TOOL_CHANGE_POSITION = 0 0 2' - 1516 Specifies the XYZ location to move to when performing a 1517 tool change if three digits are used. 1518 Specifies the XYZABC location when 6 digits are used. 1519 Specifies the XYZABCUVW location when 9 digits are used. 1520 Tool Changes can be combined. For example if you combine the 1521 quill up with change position you can move the Z first then the X and Y. 1522 1523 * 'TOOL_CHANGE_WITH_SPINDLE_ON = 1' - 1524 The spindle will be left on during the tool change when the value is 1. 1525 Useful for lathes or machines where the material is in the spindle, 1526 not the tool. 1527 1528 * 'TOOL_CHANGE_QUILL_UP = 1' - 1529 The Z axis will be moved to machine zero prior to the tool change when 1530 the value is 1. This is the same as issuing a G0 G53 Z0. 1531 1532 * 'TOOL_CHANGE_AT_G30 = 1' - 1533 The machine is moved to reference point defined by parameters 1534 5181-5186 for G30 if the value is 1. For more information see the 1535 <<gcode:parameters,Parameters Section and the 1536 <<gcode:g30-g30.1,G30 Section>>. 1537 1538 * 'RANDOM_TOOLCHANGER = 1' - 1539 This is for machines that cannot place the tool back into the pocket 1540 it came from. For example, machines that exchange the tool in the 1541 active pocket with the tool in the spindle. 1542 1543