AXIS is a graphical front-end for Machinekit which features a live preview and backplot. It is written in Python and uses Tk and OpenGL to display its user interface.

axis 2.5
Figure 1. AXIS Window

Getting Started

If your configuration is not currently set up to use AXIS, you can change it by editing the .ini file. In the section '[DISPLAY]' change the 'DISPLAY' line to read 'DISPLAY = axis'.

The sample configuration 'sim/axis.ini' is already configured to use AXIS as its front-end.

A Typical Session

  1. Start Machinekit.

  2. Reset E-STOP (F1) and turn the Machine Power (F2) on.

  3. Home all axes.

  4. Load the g-code file.

  5. Use the preview plot to verify that the program is correct.

  6. Load the material.

  7. Set the proper offset for each axis by jogging and using the Touch Off button as needed.

  8. Run the program.

To run the same program again depends on your setup and requirements. You might need to load more material and set offsets or move over and set an offset then run the program again. If your material is fixtured then you might need to only run the program again. See the Machine Menu for more information on the run command.

AXIS Display

The AXIS window contains the following elements:

  • A display area that shows one of the following:

    • a preview of the loaded file (in this case, 'axis.ngc'), as well as the current location of the CNC machine’s 'controlled point'. Later, this area will display the path the CNC machine has moved through, called the 'backplot'

    • a large readout showing the current position and all offsets.

  • A menu bar and toolbar that allow you to perform various actions

  • 'Manual Control Tab' - which allows you to make the machine move, turn the spindle on or off, and turn the coolant on or off if included in the ini file.

  • 'MDI Tab' - where G-code programs can be entered manually, one line at a time. This also shows the 'Active G Codes' which shows which modal G Codes are in effect.

  • 'Feed Override' - which allows you to scale the speed of programmed motions. The default maximum is 120% and can be set to a different value in the ini file. See the Integrator Manual for more information on this setting.

  • 'Spindle Override' - which allows you to scale the spindle speed up or down.

  • 'Jog Speed' - which allows you to set the jog speed within the limits set in the ini file. See the Integrator Manual for more information on the ini file.

  • 'Max Velocity' - which allows you to restrict the maximum velocity of all programmed motions (except spindle synchronized motion).

  • A text display area that shows the loaded G-Code.

  • A status bar which shows the state of the machine. In this screen shot, the machine is turned on, does not have a tool inserted, and the displayed position is 'Relative' (showing all offsets), and 'Actual' (showing feedback position).

Some menu items might be grayed out depending on how you have your .ini file configured. For more information on configuration see the Integrator Manual.

File Menu

  • 'Open…​' - Opens a standard dialog box to open a g code file to load in AXIS. If you have configured Machinekit to use a filter program you can also open it up. See the Integrator manual for more information on filter programs.

  • 'Recent Files' - Displays a list of recently opened files.

  • 'Edit…​' - Open the current g code file for editing if you have an editor configured in your ini file. See the Integrator Manual for more information on specifying an editor to use.

  • 'Reload' - Reload the current g code file. If you edited it you must reload it for the changes to take affect. If you stop a file and want to start from the beginning then reload the file. The toolbar reload is the same as the menu.

  • 'Save gcode as…​' - Save the current file with a new name.

  • 'Properties' - The sum of the rapid and feed moves. Does not factor in acceleration, blending or path mode so time reported will never be less than the actual run time.

  • 'Edit tool table…​' - Same as Edit if you have defined an editor you can open the tool table and edit it.

  • 'Reload tool table' - After editing the tool table you must reload it.

  • 'Ladder editor' - If you have loaded Classic Ladder you can edit it from here. See the Integrator Manual on setting up Classic Ladder

  • 'Quit' - Terminates the current Machinekit session.

Machine Menu

  • 'Toggle Emergency Stop F1' - Change the state of the Emergency Stop.

  • 'Toggle Machine Power F2' - Change the state of the Machine Power if the Emergency Stop is not on.

  • 'Run Program' - Run the currently loaded program from the beginning.

  • 'Run From Selected Line' - Select the line you want to start from first. Use with caution as this will move the tool to the expected position before the line first then it will execute the rest of the code.

Do not use 'Run From Selected Line' if your g code program contains subroutines.
  • 'Step' - Single step through a program.

  • 'Pause' - Pause a program.

  • 'Resume' - Resume running from a pause.

  • 'Stop' - Stop a running program. When run is selected after a stop the program will start from the beginning.

  • 'Stop at M1' - If an M1 is reached, and this is checked, program execution will stop on the M1 line. Press Resume to continue.

  • 'Skip lines with "/"' - If a line begins with '/' and this is checked, the line will be skipped.

  • 'Clear MDI history' - Clears the MDI history window.

  • 'Copy from MDI history' - Copies the MDI history to the clipboard

  • 'Paste to MDI history' - Paste from the clipboard to the MDI history window

  • 'Calibration' - Starts a PID tuning assistant, which is mainly for servo systems. Some things can be changed on a stepper system.

  • 'Show HAL Configuration' - Opens the HAL Configuration window where you can monitor HAL Components, Pins, Parameters, Signals, Functions, and Threads.

  • 'HAL Meter' - Opens a window where you can monitor a single HAL Pin, Signal, or Parameter.

  • 'HAL Scope' - Opens a virtual oscilloscope that allows plotting HAL values vs. time.

  • 'Show Machinekit Status' - Opens a window showing Machinekit’s status.

  • 'Set Debug Level' - Opens a window where debug levels can be viewed and some can be set.

  • 'Homing' - Home one or all axes.

  • 'Unhoming' - Unhome one or all axes.

  • 'Zero Coordinate System' - Clear (set to zero) a chosen offset.

  • 'Tool touch off to workpiece' - When performing Touch Off, the value entered is relative to the current workpiece ('G5x') coordinate system, as modified by the axis offset ('G92'). When the Touch Off is complete, the Relative coordinate for the chosen axis will become the value entered. See G10 L10 in the G code chapter.

  • 'Tool touch off to fixture' - When performing Touch Off, the value entered is relative to the ninth ('G59.3') coordinate system, with the axis offset ('G92') ignored. This is useful when there is a tool touch-off fixture at a fixed location on the machine, with the ninth ('G59.3') coordinate system set such that the tip of a zero-length tool is at the fixture’s origin when the Relative coordinates are 0. See G10 L11 in the G code chapter.

View Menu

It’s all in your point of view

The AXIS display pick menu 'View' refers to 'Top', 'Front', and 'Side' views. These terms are correct if the CNC machine has its Z axis vertical, with positive Z up. This is true for vertical mills, which is probably the most popular application, and also true for almost all EDM machines, and even vertical turret lathes, where the part is turning below the tool.

The terms 'Top', 'Front', and 'Side' might be confusing however, in other CNC machines, such as a standard lathe, where the Z axis is horizontal, or a horizontal mill, again where the Z axis is horizontal, or even an inverted vertical turret lathe, where the part is turning above the tool, and the Z axis positive direction is down!

Just remember that positive Z axis is (almost) always away from the part. So be familiar with your machine’s design and interpret the display as needed.

  • 'Top View' - The Top View (or Z view) displays the G code looking along the Z axis from positive to negative. This view is best for looking at X & Y.

  • 'Rotated Top View' - The Rotated Top View (or rotated Z view) also displays the G code looking along the Z axis from positive to negative. But sometimes it’s convenient to display the X & Y axes rotated 90 degrees to fit the display better. This view is also best for looking at X & Y.

  • 'Side View' - The Side View (or X view) displays the G code looking along the X axis from positive to negative. This view is best for looking at Y & Z.

  • 'Front View' - The Front View (or Y view) displays the G code looking along the Y axis from negative to positive. This view is best for looking at X & Z.

  • 'Perspective View' - The Perspective View (or P view) displays the G code looking at the part from an adjustable point of view, defaulting to X+, Y-, Z+. The position is adjustable using the mouse and the drag/rotate selector. This view is a compromise view, and while it does do a good job of trying to show three (to nine!) axes on a two-dimensional display, there will often be some feature that is hard to see, requiring a change in viewpoint. This view is best when you would like to see all three (to nine) axes at once.

  • 'Display Inches' - Set the AXIS display scaling for inches.

  • 'Display MM' - Set the AXIS display scaling for millimeters.

  • 'Show Program' - The preview display of the loaded G code program can be entirely disabled if desired.

  • 'Show Program Rapids' - The preview display of the loaded G code program will always show the feedrate moves (G1,G2,G3) in white. But the display of rapid moves (G0) in cyan can be disabled if desired.

  • 'Alpha-blend Program' - This option makes the preview of complex programs easier to see, but may cause the preview to display more slowly.

  • 'Show Live Plot' - The highlighting of the feedrate paths (G1,G2,G3) as the tool moves can be disabled if desired.

  • 'Show Tool' - The display of the tool cone/cylinder can be disabled if desired.

  • 'Show Extents' - The display of the extents (maximum travel in each axis direction) of the loaded G code program can be disabled if desired.

  • 'Show Offsets' - The selected fixture offset (G54-G59.3) origin location can be shown as a set of three orthogonal lines, one each of red, blue, and green. This offset origin (or fixture zero) display can be disabled if desired.

  • 'Show Machine Limits' - The machine’s maximum travel limits for each axis, as set in the ini file, are shown as a rectangular box drawn in red dashed lines. This is useful when loading a new G code program, or when checking for how much fixture offset would be needed to bring the G code program within the travel limits of your machine. It can be shut off if not needed.

  • 'Show Velocity' - A display of velocity is sometimes useful to see how close your machine is running to its design velocities. It can be disabled if desired.

  • 'Show Distance to Go' - Distance to go is a very handy item to know when running an unknown G code program for the first time. In combination with the rapid override and feedrate override controls, unwanted tool and machine damage can be avoided. Once the G code program has been debugged and is running smoothly, the Distance to Go display can be disabled if desired.

  • 'Clear Live Plot' - As the tool travels in the Axis display, the G code path is highlighted. To repeat the program, or to better see an area of interest, the previously highlighted paths can be cleared.

  • 'Show Commanded Position' - This is the position that Machinekit will try to go to. Once motion has stopped, this is the position Machinekit will try to hold.

  • 'Show Actual Position' - Actual Position is the measured position as read back from the system’s encoders or simulated by step generators. This may differ slightly from the Commanded Position for many reasons including PID tuning, physical constraints, or position quantization.

  • 'Show Machine Position' - This is the position in unoffset coordinates, as established by Homing.

  • 'Show Relative Position' - This is the Machine Position modified by 'G5x', 'G92', and 'G43' offsets.

User Menu

  • 'User0' - User defined command number 1 - to

  • 'User9' - User defined command number 10

This menu will be shown but disabled unless activated in the ini file Ten user commands can be specified in the ini file.

  • '#' precedes a halcmd This will be sent and the return waited for before continuing

  • '$' precedes a system command This will be spawned to a new process and return immediately

  • No prefix before a gcode instruction

The commands can optionally be bound to the 0 - 9 keys on the keyboard Full details in the Axis Machinekit Enhancements

Help Menu

  • 'About Axis' - We all know what this is.

  • 'Quick Reference' - Shows the keyboard shortcut keys.

Toolbar buttons

From left to right in the Axis display, the toolbar buttons (keyboard shortcuts shown [in brackets]) are:

  • tool estop Toggle Emergency Stop [F1] (also called E-Stop)

  • tool power Toggle Machine Power [F2]

  • tool open Open G Code file [O]

  • tool reload Reload current file [Ctrl-R]

  • tool run Begin executing the current file [R]

  • tool step Execute next line [T]

  • tool pause Pause Execution [P] Resume Execution[S]

  • tool stop Stop Program Execution [ESC]

  • tool blockdelete Toggle Skip lines with "/" [Alt-M-/]

  • tool optpause Toggle Optional Pause [Alt-M-1]

  • tool zoomin Zoom In

  • tool zoomout Zoom Out

  • tool axis z Top view

  • tool axis z2 Rotated Top view

  • tool axis x Side view

  • tool axis y Front view

  • tool axis p Perspective view

  • tool rotate Toggle between Drag and Rotate Mode [D]

  • tool clear Clear live backplot [Ctrl-K]

Graphical Display Area

Coordinate Display

In the upper-left corner of the program display is the coordinate display. It shows the position of the machine. To the left of the axis name, an origin symbol is shown if the axis has been homed.

axis homed

A limit symbol is shown if the axis is on one of its limit switches.

axis limit

To properly interpret these numbers, refer to the 'Position:' indicator in the status bar. If the position is 'Absolute', then the displayed number is in the machine coordinate system. If it is 'Relative', then the displayed number is in the offset coordinate system. When the coordinates displayed are relative and an offset has been set, the display will include a cyan 'machine origin' marker.

axis machineorigin

If the position is 'Commanded', then it is the ideal position --for instance, the exact coordinate given in a 'G0' command. If it is 'Actual', then it is the position the machine has actually moved to. These values can differ for several reasons: Following error, dead band, encoder resolution, or step size. For instance, if you command a movement to X 0.0033 on your mill, but one step of your stepper motor or one encoder count is 0.00125, then the 'Commanded' position might be 0.0033, but the 'Actual' position will be 0.0025 (2 steps) or 0.00375 (3 steps).

Preview Plot

When a file is loaded, a preview of it is shown in the display area. Fast moves (such as those produced by the 'G0' command) are shown as cyan lines. Moves at a feed rate (such as those produced by the 'G1' command) are shown as solid white lines. Dwells (such as those produced by the 'G4' command) are shown as small pink 'X' marks.

G0 (Rapid) moves prior to a feed move will not show on the preview plot. Rapid moves after a T<n> (Tool Change) will not show on the preview until after the first feed move. To turn either of these features off program a G1 without any moves prior to the G0 moves.

Program Extents

The 'extents' of the program in each axis are shown. At the ends, the least and greatest coordinate values are indicated. In the middle, the difference between the coordinates is shown.

When some coordinates exceed the 'soft limits' in the .ini file, the relevant dimension is shown in a different color and enclosed by a box. In figure below the maximum soft limit is exceeded on the X axis as indicated by the box surrounding the coordinate value. The minimum X travel of the program is -1.95, the maximum X travel is 1.88, and the program requires 3.83 inches of X travel. To move the program so it’s within the machine’s travel in this case, jog to the left and Touch Off X again.

axis outofrange
Figure 2. Soft Limit
Tool Cone

When no tool is loaded, the location of the tip of the tool is indicated by the 'tool cone'. The 'tool cone' does not provide guidance on the form, length, or radius of the tool.

When a tool is loaded (for instance, with the MDI command 'T1 M6' ), the cone changes to a cylinder which shows the diameter of the tool given in the tool table file.


When the machine moves, it leaves a trail called the backplot. The color of the line indicates the type of motion: Yellow for jogs, faint green for rapid movements, red for straight moves at a feed rate, and magenta for circular moves at a feed rate.


Axis can optionally display a grid when in orthogonal views. Enable or disable the grid using the 'Grid' menu under 'View'. When enabled, the grid is shown in the top and rotated top views; when coordinate system is not rotated, the grid is shown in the front and side views as well. The presets in the 'Grid' menu are controlled by the inifile item [DISPLAY]GRIDS; if unspecified, the default is 10mm 20mm 50mm 100mm 1in 2in 5in 10in.

Specifying a very small grid may decrease performance.


By left-clicking on a portion of the preview plot, the line will be highlighted in both the graphical and text displays. By left-clicking on an empty area, the highlighting will be removed.

By dragging with the left mouse button pressed, the preview plot will be shifted (panned).

By dragging with shift and the left mouse button pressed, or by dragging with the mouse wheel pressed, the preview plot will be rotated. When a line is highlighted, the center of rotation is the center of the line. Otherwise, the center of rotation is the center of the entire program.

By rotating the mouse wheel, or by dragging with the right mouse button pressed, or by dragging with control and the left mouse button pressed, the preview plot will be zoomed in or out.

By clicking one of the 'Preset View' icons, or by pressing 'V', several preset views may be selected.

Text Display Area

By left-clicking a line of the program, the line will be highlighted in both the graphical and text displays.

When the program is running, the line currently being executed is highlighted in red. If no line has been selected by the user, the text display will automatically scroll to show the current line.

axis currentandselected
Figure 3. Current and Selected Lines

Manual Control

While the machine is turned on but not running a program, the items in the 'Manual Control' tab can be used to move the machine or control its spindle and coolant.

When the machine is not turned on, or when a program is running, the manual controls are unavailable.

Many of the items described below are not useful on all machines. When AXIS detects that a particular pin is not connected in HAL, the corresponding item in the Manual Control tab is removed. For instance, if the HAL pin 'motion.spindle-brake' is not connected, then the 'Brake' button will not appear on the screen. If the environment variable 'AXIS_NO_AUTOCONFIGURE' is set, this behavior is disabled and all the items will appear.

The Axis group

'Axis' allows you to manually move the machine. This action is known as 'jogging'. First, select the axis to be moved by clicking it. Then, click and hold the '+' or '-' button depending on the desired direction of motion. The first four axes can also be moved by the arrow keys (X and Y), PAGE UP and PAGE DOWN keys (Z), and the [ and ] keys (A).

If 'Continuous' is selected, the motion will continue as long as the button or key is pressed. If another value is selected, the machine will move exactly the displayed distance each time the button is clicked or the key is pressed. By default, the available values are '0.1000, 0.0100, 0.0010, 0.0001'

See the Configure section of the Integrator Manual for more information on setting the increments.


If your machine has home switches and a homing sequence defined for all axes the button will read 'Home All'. The 'Home All' button or the Ctrl-HOME key will home all axes using the homing sequence. Pressing the HOME key will home the current axis, even if a homing sequence is defined.

If your machine has home switches and no homing sequence is defined or not all axes have a homing sequence the button will read 'Home' and will home the selected axis only. Each axis must be selected and homed separately.

If your machine does not have home switches defined in the configuration the 'Home' button will set the current selected axis current position to be the absolute position 0 for that axis and will set the 'is-homed' bit for that axis.

See the Integrator Manual for more information on homing.

Touch Off

By pressing 'Touch Off' or the END key, the 'G54 offset' for the current axis is changed so that the current axis value will be the specified value. Expressions may be entered using the rules for rs274ngc programs, except that variables may not be referred to. The resulting value is shown as a number.

Figure 4. Touch Off

See also the 'Tool touch off to workpiece' and 'Tool touch off to fixture' options in the Machine menu.

Override Limits

By pressing Override Limits, the machine will temporarily be allowed to jog off of a physical limit switch. This check box is only available when a limit switch is tripped. The override is reset after one jog. If the axis is configured with separate positive and negative limit switches, Machinekit will allow the jog only in the correct direction. Override Limits will not allow a jog past a soft limit. The only way to disable a soft limit on an axis is to Unhome it.

The Spindle group

The buttons on the first row select the direction for the spindle to rotate: Counterclockwise, Stopped, Clockwise. Counterclockwise will only show up if the pin 'motion.spindle-reverse' is in the HAL file (it can be 'net trick-axis motion.spindle-reverse' ). The buttons on the next row increase or decrease the rotation speed. The checkbox on the third row allows the spindle brake to be engaged or released. Depending on your machine configuration, not all the items in this group may appear. Pressing the spindle start button sets the 'S' speed to 1.

The Coolant group

The two buttons allow the 'Mist' and 'Flood' coolants to be turned on and off. Depending on your machine configuration, not all the items in this group may appear.


MDI allows G-code commands to be entered manually. When the machine is not turned on, or when a program is running, the MDI controls are unavailable.

axis mdi
Figure 5. The MDI tab
  • 'History' - This shows MDI commands that have been typed earlier in this session.

  • 'MDI Command' - This allows you to enter a g-code command to be executed. Execute the command by pressing Enter or by clicking 'Go'.

  • 'Active G-Codes' - This shows the 'modal codes' that are active in the interpreter. For instance, 'G54' indicates that the 'G54 offset' is applied to all coordinates that are entered. When in Auto the Active G-Codes represent the codes after any read ahead by the interpreter.

Feed Override

By moving this slider, the programmed feed rate can be modified. For instance, if a program requests 'F60' and the slider is set to 120%, then the resulting feed rate will be 72.

Spindle Speed Override

By moving this slider, the programmed spindle speed can be modified. For instance, if a program requests S8000 and the slider is set to 80%, then the resulting spindle speed will be 6400. This item only appears when the HAL pin 'motion.spindle-speed-out' is connected.

Jog Speed

By moving this slider, the speed of jogs can be modified. For instance, if the slider is set to 1 in/min, then a .01 inch jog will complete in about .6 seconds, or 1/100 of a minute. Near the left side (slow jogs) the values are spaced closely together, while near the right side (fast jogs) they are spaced much further apart, allowing a wide range of jog speeds with fine control when it is most important.

On machines with a rotary axis, a second jog speed slider is shown. This slider sets the jog rate for the rotary axes (A, B and C).

Max Velocity

By moving this slider, the maximum velocity can be set. This caps the maximum velocity for all programmed moves except spindle-synchronized moves.

Keyboard Controls

Almost all actions in AXIS can be accomplished with the keyboard. A full list of keyboard shortcuts can be found in the AXIS Quick Reference, which can be displayed by choosing Help > Quick Reference. Many of the shortcuts are unavailable when in MDI mode.

Feed Override Keys

The Feed Override keys behave differently when in Manual Mode. The keys '12345678 will select an axis if it is programed. If you have 3 axis then ' will select axis 0, 1 will select axis 1, and 2 will select axis 2. The remainder of the number keys will still set the Feed Override. When running a program '1234567890 will set the Feed Override to 0% - 100%.

The most frequently used keyboard shortcuts are shown in the following Table

Table 1. Most Common Keyboard Shortcuts
Keystroke Action Taken Mode


Toggle Emergency Stop



Turn machine on/off


`, 1 .. 9, 0

Set feed override from 0% to 100%


X, `

Activate first axis


Y, 1

Activate second axis


Z, 2

Activate third axis


A, 3

Activate fourth axis



Select jog increment



Continuous jog



Perform homing sequence



Touch off: Set G54 offset for active axis


Left, Right

Jog first axis


Up, Down

Jog second axis


Pg Up, Pg Dn

Jog third axis


[, ]

Jog fourth axis



Open File



Reload File



Run file



Pause execution



Resume Execution



Stop execution



Clear backplot



Cycle among preset views



Rapid X Axis



Rapid Y Axis


Shift-PgUp, PgDn

Rapid Z Axis


Show Machinekit Status

AXIS includes an option which shows some of the details of Machinekit’s state. You can run this program by invoking Machine > Show Machinekit Status

axis emc status
Figure 6. Machinekit Status Window

The name of each item is shown in the left column. The current value is shown in the right column. If the value has recently changed, it is shown on a red background.

MDI interface

AXIS includes a program called mdi which allows text-mode entry of MDI commands to a running Machinekit session. You can run this program by opening a terminal and typing


Once it is running, it displays the prompt 'MDI>'. When a blank line is entered, the machine’s current position is shown. When a command is entered, it is sent to Machinekit to be executed.

This is a sample session of mdi.

$ mdi
(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
MDI> G1 F5 X1
(0.5928500000000374, 0.0, 0.0, 0.0, 0.0, 0.0)
(1.0000000000000639, 0.0, 0.0, 0.0, 0.0, 0.0)


AXIS includes a program called 'axis-remote' which can send certain commands to a running AXIS. The available commands are shown by running 'axis-remote --help' and include checking whether AXIS is running ('--ping'), loading a file by name, reloading the currently loaded file ('--reload'), running the loaded file ('--run') and making AXIS exit ('--quit').

Manual Tool Change

Machinekit includes a userspace HAL component called 'hal_manualtoolchange', which shows a window prompt telling you what tool is expected when a 'M6' command is issued. After the OK button is pressed, execution of the program will continue.

The HAL configuration file 'configs/sim/axis_manualtoolchange.hal' shows the HAL commands necessary to use this component.

hal_manualtoolchange can be used even when AXIS is not used as the GUI. This component is most useful if you have presettable tools and you use the tool table.

Important Note: Rapids will not show on the preview after a T<n> is issued until the next feed move after the M6. This can be very confusing to most users. To turn this feature off for the current tool change program a G1 with no move after the T<n>.
manual tool change
Figure 7. The Manual Toolchange Window

Python modules

AXIS includes several Python modules which may be useful to others. For more information on one of these modules, use 'pydoc <module name>' or read the source code. These modules include:

  • 'linuxcnc' provides access to the Machinekit command, status, and error channels

  • 'gcode' provides access to the rs274ngc interpreter

  • 'rs274' provides additional tools for working with rs274ngc files

  • 'hal' allows the creation of userspace HAL components written in Python

  • '_togl' provides an OpenGL widget that can be used in Tkinter applications

  • 'minigl' provides access to the subset of OpenGL used by AXIS

To use these modules in your own scripts, you must ensure that the directory where they reside is on Python’s module path. When running an installed version of Machinekit, this should happen automatically. When running 'in-place', this can be done by using 'scripts/rip-environment'.

Using AXIS in Lathe Mode

By including the line 'LATHE = 1' in the [DISPLAY] section of the ini file, AXIS selects lathe mode. The 'Y' axis is not shown in coordinate readouts, the view is changed to show the Z axis extending to the right and the X axis extending towards the bottom of the screen, and several controls (such as those for preset views) are removed. The coordinate readouts for X are replaced with diameter and radius.

Pressing 'V' zooms out to show the entire file, if one is loaded.

When in lathe mode, the shape of the loaded tool (if any) is shown.

Lathe Tool Shape

axis lathe tool

Advanced Configuration

For more information on ini file settings that can change how AXIS works see the INI File/Sections/[DISPLAY] Section of Configuration chapter in the Integrator manual.

Program Filters

AXIS has the ability to send loaded files through a 'filter program'. This filter can do any desired task: Something as simple as making sure the file ends with 'M2', or something as complicated as generating G-Code from an image.

The '[FILTER]' section of the ini file controls how filters work. First, for each type of file, write a 'PROGRAM_EXTENSION' line. Then, specify the program to execute for each type of file. This program is given the name of the input file as its first argument, and must write rs274ngc code to standard output. This output is what will be displayed in the text area, previewed in the display area, and executed by Machinekit when 'Run'. The following lines add support for the 'image-to-gcode' converter included with Machinekit:

PROGRAM_EXTENSION = .png,.gif Greyscale Depth Image
png = image-to-gcode
gif = image-to-gcode

It is also possible to specify an interpreter:

PROGRAM_EXTENSION = .py Python Script
py = python

In this way, any Python script can be opened, and its output is treated as g-code. One such example script is available at 'nc_files/'. This script creates g-code for drilling a series of holes along the circumference of a circle.

Figure 8. Circular Holes

If the environment variable AXIS_PROGRESS_BAR is set, then lines written to stderr of the form


will set the AXIS progress bar to the given percentage. This feature should be used by any filter that runs for a long time.

The X Resource Database

The colors of most elements of the AXIS user interface can be customized through the X Resource Database. The sample file 'axis_light_background' changes the colors of the backplot window to a 'dark lines on white background' scheme, and also serves as a reference for the configurable items in the display area. The sample file 'axis_big_dro' changes the position readout to a larger size font. To use these files:

xrdb -merge /usr/share/doc/emc2/axis_light_background

xrdb -merge /usr/share/doc/emc2/axis_big_dro

For information about the other items which can be configured in Tk applications, see the Tk man pages.

Because modern desktop environments automatically make some settings in the X Resource Database that adversely affect AXIS, by default these settings are ignored. To make the X Resource Database items override AXIS defaults, include the following line in your X Resources:

    *Axis*optionLevel: widgetDefault

this causes the built-in options to be created at the option level 'widgetDefault', so that X Resources (which are level 'userDefault') can override them.

Physical jog wheels

To improve the interaction of AXIS with physical jog wheels, the axis currently selected in the GUI is also reported on a pin with a name like 'axisui.jog.x'. One of these pins is 'TRUE' at one time, and the rest are 'FALSE'. These are meant to control motion’s jog-enable pins.

After AXIS has created these HAL pins, it executes the HAL file named in '[HAL]POSTGUI_HALFILE'. Unlike '[HAL]HALFILE', only one such file may be used.


If it exists, the contents of '~/.axisrc' are executed as Python source code just before the AXIS GUI is displayed. The details of what may be written in the axisrc are subject to change during the development cycle.

The following adds Control-Q as a keyboard shortcut for Quit.

root_window.bind("<Control-q>", "destroy .")
help2.append(("Control-Q", "Quit"))


Upon initialisation, Axis creates several HAL pins which can be used externally.

  • axisui.jog.x (also y z a b c u v w) is an OUT bit pin set TRUE if that axis is currently the selected axis for jogging in the Axis GUI

  • axisui.jog.increment is an OUT float pin set true if in incremental jog mode, set 0 if in continous mode. If in incremental mode, the value of the pin is the increment selected eg. In metric mode, value of 5.000000 = 5mm increments, 0.500000 = 0.5mm increments

  • axisui.notifications-clear-info is an IN bit pin, which if set TRUE will clear all info text from the Axis GUI notification area (bottom right corner)

  • axisui.notifications-clear-error is an IN bit pin, which if set TRUE will clear all error text from the Axis GUI notification area (bottom right corner)

  • axisui.notifications-clear is an IN bit pin, which if set TRUE will clear ALL text from the Axis GUI notification area (bottom right corner) Same as using Ctrl Space from the keyboard

  • is an IN bit pin, which if set TRUE will prevent Axis running a program. An example of its use would be to connect it to a machine safety screen interlocks, thereby allowing jogging, touch off etc. but preventing a program running until the screens are back in place.

Some of these pins can be useful in synchronising pyvcp or gladevcp panels which duplicate some of the functions of Axis.

External Editor

The menu options File > Edit…​ and File > Edit Tool Table…​ become available after defining the editor in the ini section [DISPLAY]. Useful values include EDITOR=gedit and EDITOR=gnome-terminal -e vim. For more information, see the DISPLAY section of the INI Configuration Chapter in the Integrator Manual.

Virtual Control Panel

AXIS can display a custom virtual control panel in the right-hand pane. You can program buttons, indicators, data displays and more. For more information, see the Integrator Manual.

Axis Preview Control

Special comments can be inserted into the G Code file to control how the preview of AXIS behaves. In the case where you want to limit the drawing of the preview use these special comments. Anything between the (AXIS,hide) and (AXIS,show) will not be drawn during the preview. The (AXIS,hide) and (AXIS,show) must be used in pairs with the (AXIS,hide) being first. Anything after a (AXIS,stop) will not be drawn during the preview.

These comments are useful to unclutter the preview display (for instance while debugging a larger g-code file, one can disable the preview on certain parts that are already working OK).

  • (AXIS,hide) Stops the preview (must be first)

  • (AXIS,show) Resumes the preview (must follow a hide)

  • (AXIS,stop) Stops the preview from here to the end of the file.

  • (AXIS,notify,the_text) Displays the_text as an info display This display can be useful in the Axis preview when (debug,message) comments are not displayed.

The preview display can be completely disabled for all loaded files by an ini file field

Full details in the below