Starting Machinekit

Running Machinekit

Machinekit is started with the script file 'machinekit'.

machinekit [options] [<ini-file>]
machinekit script options
  • '-v' = verbose - prints info as it works

  • '-d' = echoes script commands to screen for debugging

If the machinekit script is passed an ini file it reads the ini file and starts Machinekit. 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 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 machinekit 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.

configuration selector
Figure 1. Configuration Selector

Files Used for Configuration

Machinekit 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.[1] 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 Machinekit 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 Machinekit 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 Machinekit. It is normally setup to run all of the communication within a single computer but can be modified to communicate between several computers.

  • 'machinekitrc' This file saves user specific information and is created to save the name of the directory when the user first selects an Machinekit configuration.[2]

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


Twopass parsing of .hal files is retained for backward compatibility. It could be removed without notice. Since the introduction of Instantiated Components which can be created at any time during the start up period or even later, it has been rendered redundant.

Machinekit supports TWOPASS processing of hal configuration files that can help in the modularization and readability of hal files. (Hal files are specified in an Machinekit 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 in the [HAL] section:


TWOPASS = anystring

Where "anystring" 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.

The TWOPASS option can be specified with options to add output for debugging (verbose) and to prevent deletion of temporary files (nodelete). The options are separated with commas.



TWOPASS = on,verbose,nodelete

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.

Twopass processing occurs before the loading of a gui. When using a [HAL]POSTGUI_HALFILE, it is convenient to place all the loadrt statements for components needed in a halfile that is loaded earlier.

Example of a HAL section when using a POSTGUI_HALFILE :


HALFILE = core_sim.hal
HALFILE = sim_spindle_encoder.hal
HALFILE = axis_manualtoolchange.hal
HALFILE = simulated_home.hal
HALFILE = load_for_postgui.hal  <-- loadrt lines for components in postgui.hal

POSTGUI_HALFILE = postgui.hal
HALUI = halui

Examples of TWOPASS usage for a simulator are included in the directories:


1. 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.
2. Usually this file is in the users home directory (e.g. /home/user/ )