1. Running LinuxCNC

LinuxCNC is started with the script file linuxcnc.

linuxcnc [options] [<ini-file>]
linuxcnc script options

  • -v = verbose - prints info as it works

  • -d = echoes script commands to screen for debugging

If the linuxcnc script is passed an ini file it reads the ini file and starts LinuxCNC. The ini file [HAL] section specifies the order of loading up HAL files if more than one is used. Once the HAL=xxx.hal files are loaded then the GUI is loaded then the POSTGUI=.xxx.hal file is loaded. If you create PyVCP or GladeVCP objects with HAL pins you must use the postgui HAL file to make any connections to those pins. See the HAL section of the INI configuration for more information.

Configuration Selector

If no ini file is passed to the linuxcnc script it loads the configuration selector so you can choose and save a sample configuration. Once a sample configuration has been saved it can be modified to suit your application.

images/configuration-selector.png
Figure 1. Configuration Selector

2. Files Used for Configuration

LinuxCNC is configured with human readable text files. All of these files can be read and edited in any of the common text file editors available with most any Linux distribution.
[Don’t confuse a text editor with a word processor. A text editor like gedit or kwrite produce files that are plain text. They also produce lines of text that are separated from each other. A word processor like Libre Office produces files with paragraphs and word wrapping and lots of embedded codes that control font size and such. A text editor does none of this.]
 You’ll need to be a bit careful when you edit these files. Some mistakes will cause the start up to fail. These files are read whenever the software starts up. Some of them are read repeatedly while the CNC is running.

Configuration files include

  • INI The ini file overrides defaults that are compiled into the LinuxCNC code. It also provides sections that are read directly by the Hardware Abstraction Layer.

  • HAL The HAL files start up process modules and provide linkages between LinuxCNC signals and specific hardware pins.

  • VAR The var file is a way for the interpreter to save some values from one run to the next. These values are saved from one run to another but not always saved immediately. See the Parameters section of the G Code Manual for information on what each parameter is.

  • TBL The tbl file saves tool information. See the User Manual Tool File section for more info.

  • NML The nml file configures the communication channels used by the LinuxCNC. It is normally setup to run all of the communication within a single computer but can be modified to communicate between several computers.

  • linuxcncrc This file saves user specific information and is created to save the name of the directory when the user first selects an LinuxCNC configuration.
    [Usually this file is in the users home directory (e.g. /home/user/ )]

Items marked (in HAL) are used by the sample HAL files and are suggested as a good convention. Other items are used by LinuxCNC directly, and must always have the section and item names given.

3. TWOPASS

LinuxCNC 2.5 supports TWOPASS processing of hal configuration files that can help in the modularization and readability of hal files. (Hal files are specified in an LinuxCNC ini file in the HAL stanza as [HAL]HALFILE=filename).

Normally, a set of one or more hal configuration files must use a single, unique loadrt line to load a kernel module that may handle multiple instances of a component. For example, if you use a two input AND gate component (and2) in three different places in your setup, you would need to have a single line somewhere to specify:

   loadrt and2 count=3

resulting in components and2.0, and2.1, and2.2.

Configurations are more readable if you specify with the names=option for components where it is supported, e.g.,:

loadrt and2 names=aa,ab,ac

resulting in components aa,ab,ac.

It can be a maintenance problem to keep track of the components and their names since when you add (or remove) a component, you must find and update the single loadrt directive applicable to the component.

TWOPASS processing is enabled by including an ini file parameter:

[HAL]TWOPASS=anything

Where "anything" can be any non-null string. With this setting, you can have multiple specifications like:

loadrt and2 names=aa
...
loadrt and2 names=ab,ac
...
loadrt and2 names=ad

These commands can appear in different HALFILES. The HALFILES are processed in the order of their appearance in the ini file.

With TWOPASS processing, all [HAL]HALFILES are first read and multiple appearances of loadrt directives for each module are accumulated. No hal commands are executed in this initial pass.

After the initial pass, the modules are loaded automatically with a number equal to the total number when using the count= option or with all of the individual names specified when using the names= option.

A second pass is then made to execute all of the other hal instructions specified in the HALFILES. The addf commands that associate a component’s functions with thread execution are executed in the order of appearance with other commands during this second pass.

While you can use either the count= or names= options, they are mutually exclusive — only one type can be specified for a given module.

TWOPASS processing is most effective when using the names= option. This option allows you to provide unique names that are mnemonic or otherwise relevant to the configuration. For example, if you use a derivative component to estimate the velocities and accelerations on each (x,y,z) coordinate, using the count= method will give arcane component names like ddt.0, ddt.1, ddt.2, etc.

Alternatively, using the names= option like:

loadrt ddt names=xvel,yvel,zvel
...
loadrt ddt names=xacel,yacel,zacel

results in components sensibly named xvel,yvel,zvel, xacel,yacel,zacel.

Many comps supplied with the distribution are created with the comp utility and support the names= option. These include the common logic components that are the glue of many hal configurations.

User-created comps that use the comp utility automatically support the names= option as well. In addition to comps generated with the comp utility, numerous other comps support the names=option. Comps that support names= option include: at_pid, encoder, encoder_ratio, pid, siggen, and sim_encoder.

Examples of TWOPASS usage for a simulator are included in the configs/simtcl directory.