Written Tutorials

Compiling LinuxCNC from Source Code

There have been people to ask the question of how to run LinuxCNC on a Linux distribution of their choice. This is possible and actually a fairly simple thing to do. If you want to run LinuxCNC as a simulator for gcode, then you can start right away, but if you wish to use LinuxCNC as a controller, it only becomes a little more complicated because you have to have a realtime kernel for it to work properly. I addressed how to compile a realtime kernel using the PREEMPT_RT patch in a separate tutorial. You can find the written tutorial on my webpage at the following address: http://myheap.com/cnc-stuff/linuxcnc-emc2.html. You can read the tutorial there by following the link or download a PDF version of the tutorial by clicking on the PDF icon next to the title. Additionally, I made a video tutorial of the process as part of the LinuxCNC for the Home Hobbyist series. You can find a link to watch the video on the same page as above, or you can watch it on YouTube by using this link: https://www.youtube.com/watch?v=RjTfKF7gcIo. If your intention is to use LinuxCNC as a controller of a machine, I encourage you to take a look at the above tutorial and video.

This tutorial is based on Lubuntu 18.04 32-bit version. This distribution was selected do to its lightweight desktop. While this is not the newest release of Lubuntu, it is the newest available LTS (Long Term Support) available at the time of this writing.

The computer I prepared for use with this tutorial has Lubuntu 18.04 i386 installed on it using the normal installation option with the download updates while installing box checked. After installation all updates were completed and the system rebooted. To finish setting up the computer, a realtime kernel was compiled using the PREEMPT_RT patch and installed on the machine.

Getting the computer ready

We will need the source code repository from Ubuntu to perform some of the work which we will need to do. To add the source code repository in Lubuntu, click the menu button → System Tools → Synaptic Package Manager. You will need to enter your password and click OK to open the software. We need to make two changes here. The first one will add the source code repository to our list of repositories. Click Settings from the top menu and select repositories from the sub-menu. A dialog will open up with several tabs across the top of it. The first tab reads Ubuntu Software, on this tab, locate the line that reads Source code and check the box to indicate that we want software from that repository. The second change we want to make is to inform Lubuntu that we do not want to do any upgrades to a newer version of Ubuntu. If we did, we would lose our realtime kernel and the LinuxCNC controller would not work for us anymore. Locate the third tab on the top that reads Updates and click on it. On this page where it reads “Notify me of a new Ubuntu Version” click the drop down box and select Never from the list. With our changes out of the way click the close button on the dialog. Lubuntu will then inform you that its list of repositories has changed. Click the reload button to reload the repositories into Lubuntu. We are finished with Synaptic Package Manager so go ahead and close it.

With that out of the way, we will now update the system to make sure everything is ready to go. Open a terminal either using the shortcut icon or by pressing [CTRL][ALT][T] on the keyboard. Now in your terminal enter the following command:

sudo apt update

This command checks for any changes in the software repositories and compares its software list to the software we have installed on the computer. Remember, we are potentially making changes to the system and will have to provide our password. When it is complete, apt will notify you if there are newer software versions available. Let’s go ahead and update anything out there before we start on compiling LinuxCNC by issuing the following command:

sudo apt dist-upgrade

The dist-upgrade directive passed to apt tells apt that we want to upgrade our software but unlike using just upgrade, dist-upgrade will also handle any changing dependencies from old software to the new software.

Finally, this tutorial assumes that you have compiled your own realtime kernel. If you have you are all set. If you have not compiled a realtime kernel because you are only interested in running LinuxCNC as a gcode simulator then we will need to install the software compiler to permit the computer to compile the LinuxCNC source code. You can install the compiler with the following command:

sudo apt install build-essential

With the preliminary work completed with the computer, we can carry on.

Getting the LinuxCNC Source Code

We will start this adventure by getting the LinuxCNC source code. The LinuxCNC source is hosted on a site called github. Github specializes in storing and tracking the changes to source code for different projects, and you can get the code in one of two ways. First you could open your browser and navigate to https://github.com/LinuxCNC/linuxcnc, select the branch you are interested in and click the Clone or download button, or you can use the git application and get it all. In this tutorial I will use git to download the LinuxCNC source code as it allows easy switching from the current development source tree to the stable 2.7 source tree as you please. Like most things in the Linux world, we will need to install some software to make this happen.

Open a terminal by pressing [CTRL][ALT][T] or clicking the launcher for the terminal if you don’t already have it open. For the duration of this tutorial we will be working within the terminal environment. Also as a side note, there will be a video of this tutorial that you can watch to help clarify issues that may arise. Now that we have a terminal open, we need to install the git software that will download and manage the source code for us. Enter the following command in the terminal.

sudo apt install git

Because we are installing software that potentially makes changes to the system, we have to run the sudo command. When you press enter the computer will ask for your password and then offer to install the related packages. Enter Y and press the enter key and let it do its thing.

Now that we have the git software installed we can use it to download the LinuxCNC source code from the github website. Git is software for managing revision histories of file and is mostly used with source code. While we are only going to use it to retrieve and select a particular branch of the LinuxCNC software, it is good to keep in mind that it can do much, much more. I will leave those things for you to discover on your own. To download the LinuxCNC source code in the terminal, type the following command.

git clone git://github.com/linuxcnc/linuxcnc.git linuxcnc-dev

The above command runs the git program. The parameter clone means we wish to get a full copy of the source code, or a clone of it as you will. The next part, git://github.com/linuxcnc/linuxcnc.git tells the software where the repository is located and finally, the linuxcnc-dev tells git that we want it copied into a folder called linuxcnc-dev. Git will give you some status messages while it does its job and when it is finished will return you to the prompt.

Now if you type the ls command in the terminal you will see a new folder called linuxcnc-dev that contains the code we downloaded. Now let’s change to the linuxcnc-dev folder by using the following command.

cd linuxcnc-dev

What version of LinuxCNC to compile

We have reached a point where we need to decide what version of LinuxCNC that we wish to compile. Recall I told you that Git manages changes in files and is typically used for computer source code. Git also allows you to branch your source code to work on things without affecting your previous work. When you are satisfied with your new work, git can be used to merge the new stuff with the old stuff. Now the developers at LinuxCNC use this feature to keep what they are working on currently separated from the stuff that they have already written and is considered stable. At the time of this writing the main development software called 2.8 pre1 is located in the main branch on git. This main branch is referred to as the master branch or just master. The last stable release of LinuxCNC is version 2.7.x. This is managed as a separate branch in git called simply 2.7. By default when we download the source code git will be pointing to the master branch or version 2.8 pre1. If you want to compile the stable 2.7 version of LinuxCNC, we will need to tell git to switch to that branch of code. Doing this is as simple as telling git that you want to use that branch. To select the 2.7 branch use the following command:

git checkout 2.7

If you change your mind and decide you would rather compile the 2.8 pre1 version of LinuxCNC, then simply check that branch back out. Remember the newest version of the LinuxCNC software is called master. You can do that with the following command:

git checkout master

The checkout command given to git tells git that you want to use a specific branch of code. In the example above the 2.7 branch for LinuxCNC 2.7 or the master branch for LinuxCNC 2.8 pre1.

One last thing before continuing that I want to mention is that LinuxCNC sometimes is very actively developed and things can be added or changed relatively quickly. Because of this, I would recommend that you use git to retrieve any changes to the source code since you initially cloned the repository. We just cloned the source so there isn’t likely to be any changes, but if it has been a few days since you cloned the repository, it would be good check anyway.

To update our source code with any changes that may have happened on the LinuxCNC GitHub repository we only need to run the following command.

git pull

The pull command will get any changes and merge them with the code we have for the branch we have checked out. To clarify this, say we have checked out branch 2.7 with the command git checkout 2.7, then when we use the command git pull, any changes that have been made to the 2.7 branch source code will be merged with ours. It would be a good idea to run gut pull any time you change branches of source code.

Now that I have covered all that, decide which version you want to compile, check out the appropriate branch and do a pull to make sure you have the most updated code.

Installing the required dependencies

Just like when we compiled the Linux Kernel, LinuxCNC will require some additional software to be installed before we can compile it. This software, in programming parlance, is called build dependencies. Determining which software you need can be easy or a little tricky depending on which distribution of Linux you have selected. If you have a Debian based Linux distribution, then the developers have provided meta-data that will examine your system and list the various packages that you will need to install to allow the computer to build the software. To be able to utilize this feature we will need to again install a bit of extra software. Install the devscripts, dpkg-dev and python software by using the following command in your terminal.

sudo apt install devscripts dpkg-dev python

Because we are making changes to the system, we again use the sudo command. Enter your password if prompted. If the package is already installed apt will inform you that you already have it. Otherwise apt will install the software. Now to determine what dependencies that need to be installed we need to move to the debian directory and run the configuration script. Change to the debian directory by issuing the following command:

cd ~/linuxcnc-dev/debian

The configure script located in this directory configures the debian packaging. It must be run if you want to either get the system to give you a list of dependencies or if you want to create a debian package files that can be installed on the system. The script takes several options but the only one we will concern ourselves with is the uspace option. Uspace tells the script that we will be building for either a PREEMPT_RT realtime system or a non-realtime system. These are compatible for our needs. Now issue the command:

./configure uspace

If all went well, you should see a message that reads “successfully configured for ‘uspace-Ubuntu-18.04’” To get a list of dependencies that we need to install, we will run the dpkg-checkbuilddeps tool. This program will need to be run from the linuxcnc-dev folder. Move to this folder by entering the following command:

cd ..

This command changes the directory and the two dots mean move up to the parent folder. Now lets run the dependency check by running the following command.


The output of this command will list all the software packages that need to be installed to successfully compile the LinuxCNC software. You can install them with the following command:

sudo apt install <package name>

You can install multiple packages at the same time by specifying the packages separated by spaces, like so:

sudo apt install <package name> <package name> <...> …

Depending on whether you want to compile the LinuxCNC 2.8 pre1 version or the 2.7 version the dependencies may differ slightly. Below is a list of dependencies that can be installed that will take care of every scenario in this tutorial. You can copy and paste the section of code in your terminal to install all of them at the same time.

sudo apt install debhelper dh-python libudev-dev libxenomai-dev \
tcl8.6-dev tk8.6-dev libreadline-gplv2-dev asciidoc \
dvipng graphviz groff imagemagick inkscape python-lxml \
source-highlight texlive-font-utils texlive-lang-cyrillic \
texlive-lang-french texlive-lang-german texlive-lang-polish \
texlive-lang-spanish w3c-linkchecker python-dev python-tk \
libxmu-dev libgtk2.0-dev intltool libboost-python-dev \
libusb-1.0-0-dev yapps2 libglu1-mesa-dev libgl1-mesa-dev \
dblatex docbook-xsl texlive-extra-utils texlive-fonts-recommended \
texlive-latex-recommended xsltproc gettext autoconf libmodbus-dev \
asciidoc-dblatex libxaw7-dev bwidget libtk-img tclx python-gtk2

After entering your password, if asked, press Y to install the packages. There is a lot of software to install, so stretch your legs and get a beverage of your choice. When it has finished come back here.

Another Decision to make … Compile Uspace or deb packages

Now that the required dependency packages are installed, it is time for you to make another decision. Do you want to compile the software for a RIP Environment, which means run in place, or do you want installable debian packages? Let me briefly talk about the difference between the two.

The Run In Place (RIP) environment does not install any software on the computer, but instead leaves the compiled software in the source tree. Running the software will require you to source a script called rip-environment each time you log into the system. The script sets up the computers environment to allow the software to run, by adding relevant paths and other information. This is considered the developers environment because you can compile multiple versions of the LinuxCNC software and at any time run whichever you please.

Compiling debian install packages on the other hand is considered the user friendly route. It will create the binary and documentation deb packages that you can install on the computer that give you the well known cnc menu entry with shortcuts to start the software. This is what you would see if you are familiar with the current live install CD available from the linuxcnc.org website.

The choice to compile either the RIP environment or debian package option of LinuxCNC is your choice. I will cover both in this tutorial. Simply go to the heading that matches your decision.

Compiling LinuxCNC for the RIP Environment

This section of the tutorial explains how to compile LinuxCNC for a Run In Place (RIP) Environment. If you want to see how to compile LinuxCNC for installable Debian packages, see the heading below titled, “Compiling LinuxCNC for Debian Packages”.

Now that all the dependencies are installed we can now begin compiling LinuxCNC. At this point you should be in the linuxcnc-dev folder. To compile the software we need to change into the src directory. Do this by entering the following command:

cd src

Now that we are in the src directory we can start. First we will run the autogen.sh script. Its job is to create the configure script that will be used to configure LinuxCNC software for compilation. Enter the command:


It will appear that nothing happened, but in the background, the configure script will have been created. The configure script configures how the source code will be compiled and there are many options you can use. I will briefly examine and talk about only two of them. These options are --with-realtime and --enable-build-documentation.

The first option --with-realtime tells the configure script what realtime system you are using. For example, preempt_rt, xenomai or rtai. In our case, we will either want to compile LinuxCNC as a simulator using the installed vanilla kernel, or we will want to compile LinuxCNC as a machine controller using the PREEMPT_RT realtime kernel that we installed. Fortunately for us, the value to use with --with-realtime is the same. That option will be called uspace. If you are interested in using a different --with-realtime option, for an RTAI kernel, for example, please see the configure documentation. Issuing a ./configure -h will show all the options.

The Second option, --enable-build-documentation requires no arguments. If you want to build the LinuxCNC documentation along with the executables then add this option to the configure switch. Building the documentation does take a little longer to complete, so if you’re not interested in having a local copy built, feel free to leave it off.

Now that we know what the options are we can compile the software. I will include the latest documentation with the build, so in the terminal issue the following command:

./configure --with-realtime=uspace --enable-build-documentation

The configure script will check the system looking for all the dependencies required to build the software. If any are missing, it will error and tell you what needs to be installed. If all went well, you will get a notification in a big box telling you that the configure script completed successfully. Now that we are done configuring LinuxCNC, we can compile it. Now, before we compile, I should remind you that the make program can utilize multiple processor cores. Using multiple cores will speed up the process somewhat. To tell make to use multiple cores we pass it the -j flag along with the number of cores we would like it to use. If you are unsure how many cores your computer has type the following command:


The result will be a number indicating how may processor cores are available. Say for example, your computer returned the value of 2. We can tell make to use both cores by passing -j2 on the command line, for example:

make -j2

Will run make and compile using 2 cores. Choose whatever selection you want here and let the software compile. For example:


Compiling the LinuxCNC software and documentation will take a bit of time. Nothing like compiling the realtime kernel, but you will still have enough time get a drink and relax. Come back when the compile is finished.

Giving permissions to LinuxCNC

Now that the software is compiled, we only need to run another command to have a complete LinuxCNC system. LinuxCNC will need permission to access the hardware on the computer if you are running in realtime. To do this we will run make with the setuid option. Because this changes the file to run as root and sets the sticky bit, it will have to be run with elevated privileges. To do this, enter the following command:

sudo make setuid

Everything is now in place to start using your newly compiled LinuxCNC system. Now, what we finished compiling here is what is called Run In Place or RIP. And to use it, we must source the environment before running any of the LinuxCNC software. To do this, we can issue the command:

source ~/linuxcnc-dev/scripts/rip-environment

This command will source variable that are needed by LinuxCNC to run properly. Keep in mind that you have to do this every time you log into the machine.

Most of the software will be located in either the bin or scripts directories. Paths to these are created for you when you source the rip-environment script. Enjoy your newly compiled LinuxCNC software.

Compiling LinuxCNC for Debian Packages

This section describes how to compile LinuxCNC to create installable Debian packages. If you are interested in compiling LinuxCNC for use in a Run In Place please see the section above titled, “Compiling LinuxCNC for the RIP Environment”.

Compiling LinuxCNC to make Debian packages is almost too easy to believe. At this point all the dependencies have been installed. We only have a couple more things to do to get the job done. You should be in the linuxcnc-dev folder to complete these steps. If not enter the following command in the terminal.

cd ~/linuxcnc-dev

We will use a program called dpkg-checkbuilddeps to get the system ready to build the Debian install packages. This program checks the installed packages in the system against the build dependencies and build conflicts listed in the control file. If there are any issues it will report them and exit. For example, if you are missing any of the required programs required to build the software. Since we installed all the build dependencies in the last step, it should return nothing to us. Enter the following command in the terminal.


When dpkg-checkbuilddeps has finished running we only need to issue one more command to kick off the job. Enter the following command in the terminal.

debuild -uc -us

The debuild program will configure LinuxCNC and compile it and its documentation. The process does take a little while to complete. When it has finished you will find several .deb files in your home directory.

Installing the Deb packages

Now that the software has been compiled and made into installable Debian packages you are free to install them. When debuild creates the packages, you will end up with several located in your home directory. When compiling LinuxCNC version 2.7 I got the following packages. I have listed them below with a short description of what each is.

linuxcnc-doc-en_2.7.14_all.deb – LinuxCNC documentation in English
linuxcnc-doc-es_2.7.14_all.deb – LinuxCNC documentation in Spanish
linuxcnc-doc-fr_2.7.14_all.deb – LinuxCNC documentation in French
linuxcnc-uspace_2.7.14_i386.deb – LinuxCNC software for i386 (32bit system)
linuxcnc-uspace-dev_2.7.14_i386.deb – LinuxCNC development files for i386 (32bit system)

You can install the deb files in a couple of ways. You can install them from command line by using a command like the following:

sudo apt install ~/linuxcnc-uspace_2.7.14_i386.deb

The above command tells the apt program to install the package located in the home folder named linuxcnc-uspace_2.7.14_i386.deb. Another method of installing the deb files is to open the file browser and double click the deb file and have the graphical package installer install the package for you.

Installing from the deb file will place an entry in the menu with relevant links to LinuxCNC and its documentation.

I hope this tutorial has removed some of the mystery of compiling LinuxCNC from source code. Thank you for participating.

Last Update 29 MAY 2019

Compiling a Realtime Linux kernel with the preemp-rt kernel patch

LinuxCNC requires a realtime kernel in which to run. Most Linux distributions do not have the option to install a prebuilt realtime kernel. As a result, if you want something other than the default LinuxCNC distribution you will have to take matters into your own hands. This document will show you how to compile and install a new kernel that has been patched with the realtime preempt-rt patch.

This tutorial is based on Lubuntu 18.04 32-bit version. This distribution was selected do to its lightweight desktop. While this is not the newest release of Lubuntu, it is the newest available LTS (Long Term Support) available at the time of this writing.

Prior to following this tutorial I have installed Lubuntu 18.04 32-bit using the normal installation option and also checked the download updates while installing. After installation all updates were completed and the system rebooted.

Installing the required software for compiling a kernel

Before you can compile a kernel, you will need to install some additional software. This will include the following packages: build-essential, curses, bison, flex and the ssl libraries. These software packages include the compiler, libraries and additional tools that the system will need to complete the compilation of the kernel. To install them on your system open a terminal and type in the following command, or copy and paste into your terminal.

sudo apt install build-essential libncurses-dev bison flex libssl-dev

Now that the computer has the required software installed to compile the kernel, the next step is to create a place to do the work. For our purposes we will create a folder on the hard disk and do all the work required from this folder. If you still have your terminal open, and if not you will need to open it. (Note: all the work we will be doing will be from the terminal.) and issue the following commands:

mkdir rtkernel

The above command will create a directory named rtkernel. This directory or folder is where we will be working from to keep the system tidy.

cd rtkernel

The above command will change you into the rtkernel directory

Downloading the Kernel source and the preempt-rt patch

Now that we have created a place to work from it is time to download the Kernel source code and the preempt-rt kernel patch. One thing to keep in mind is that there kernel version that we wish to compile and the patch version have to match, viz. Be the same version number. I would also recommend compiling a kernel with the same major version number as the kernel that is currently running on your system. To find the version number of the kernel currently running on your system, type the following command in your terminal.

uname -r

The above command will spit out some numbers and perhaps some text. For example, on my machine I get the following output.


This indicates that I am running kernel version 4.18.0. What I want to take note of here is the first number. The number 4 tells me that this is version 4 of the kernel and we will use that version in our tutorial.

Before we actually download the kernel and patch, keep in mind that the current kernel source code may be at a slightly higher version than the newest release of the preempt-rt patch. Because of this, we will get the patch first and then get the corresponding kernel source code.

Open your browser and navigate to https://wiki.linuxfoundation.org/realtime/start. At the time of this writing, you can get to the two latest realtime patches from the main page of the site, but in the event that the page changes or you need an older version of the patch we will navigate to where we can find links to the patches. On the main page under the heading Versions of PREEMPT-RT patches you will see the two newest versions of the patch available. Under these is a link titled Read more about PREEMPT_RT versions. Clicking this link will open another page. On the right hand side you will see a list of actively maintained preempt_rt versions. At the time of this writing there are four separate versions of the kernel version 4 of the patch. The newest is 4.19. That is the one in which I will use. Clicking on these links will open a page that will allow you to download the code. Here you will see several files. There are basically two types of files here. The compressed patch and a signature for each compressed file. You have the option of selecting you favorite compressed format. But rather than clicking the file and downloading it somewhere then having to move it, we will do this a little different. Find the patch that ends with the .gz extension, right click and select copy link location. This will copy the url to the file to your computers clip board. Now go back to the teminal window and type wget and then a space and right click your mouse and select paste, or alternatively, press the [CTRL][ALT][V] keys to paste into the terminal. You should get something that looks like the following:

wget http://cdn.kernel.org/pub/linux/kernel/projects/rt/4.19/patch-4.19.37-rt19.patch.gz

Now press the enter key and the computer will download the patch to our current directory, rtkernel. It will only take a couple of seconds or so to download. While you are at it, note the version number of the patch you downloaded. In the above example, the version is 4.19.37. This will be the version of the kernel we will want to download as well.

With the patch downloaded it is time to get the kernel source code. Go back to your browser and navigate to https://www.kernel.org. When the page opens you will see several kernel versions available that you could download. These are the current list of the newest kernel releases for different kernel versions. If one of them is the same version as the patch you downloaded, then simply right click the “tarball” link next to it and select copy link location like we did above. But more than likely, the version that is available on the main page will be just slightly newer than the version of the patch you were able to download. If you fall into that category then don’t despair, we just have to make a few click to get the kernel we want. At the top of the page you will see a protocol and location list. Click on the link next to https and it will open page with a list of directories. Click the linux link on this page and another will open with yet another list of directories. On this page click the kernel link. Finally on the page that opens click the v4.x link for a list of all the version 4 kernel source code archives. Now this page is quite long. Scroll down the page until you find the files that start with linux. These are the kernel source code files. Look for the file that says kernel-.tar.gz. So in our case we are looking for linux-4.19.37.tar.gz. When you find it, right click the file with your mouse and select copy link location like we done for the patch. Now in your terminal, type wget and a space, then either right click your mouse and select paste or press [CTRL][ALT][V] on your keyboard to paste in the terminal. This will give you a command that looks something like the following.

wget https://mirrors.edge.kernel.org/pub/linux/kernel/v4.x/linux-4.19.37.tar.gz

When you press enter, the wget program will go and retrieve the file for you.

Extracting and patching the kernel source code

Now that the source code for the kernel and the patch have been downloaded, we can extract and apply the patch. Doing an ls command in the terminal should like the files we have downloaded. In the terminal type:


This should give you a result that looks something like:

These are the two files that we downloaded. First we will extract the kernel source code with the following command:

tar xvf linux-4.19.37.tar.gz

This will take a moment or two depending on how fast your system is. When it is compete, if you do a ls command now, you will see that a directory called linux-4.19.37 was created. Next we want to unzip the patch file we downloaded. We will do this with the gunzip program. Type the following in the terminal:

gunzip patch-4.19.37-rt19.patch.gz

Now if you ls the directory you see patch is there but the .gz is gone from the end, indicating that it is now unzipped.

From here on out we will be working from within the linux kernel source code directory. Change to this directory by issuing the following command in the terminal

cd linux-4.19.37

Now that we are in the kernel source tree we need to patch the kernel source with the preempt-rt patch. In the terminal type the following command.

patch -p1 < ../patch-4.19.37-rt19.patch

You will see some stuff fly up the screen indicating the files that are being patched. When it is complete we can proceed.

Now that the kernel is patched we only need to make sure the source tree is free from any remnants of any build that may be left there for some reason. To do this we will issue the following command in the terminal.

make mrproper

Make is a command that can take different directives depending on what is in the makefile. The mrproper directive in the kernels makefile will clean anything from the source tree that would adversely affect compilation of the kernel. You should always run this command before starting any work on the kernel for the first time. If you are interested in what command are available for making the Linux Kernel type make help in the terminal. You will be given a list of options that are available.

Copying a starting configuration to use with the kernel

If we were to compile the kernel now, there is no telling what would be included in the new kernel. We have to provide it some configuration. Fortunately we have a working kernel now so we can use its configuration as a basis. If we run the following command:

ls /boot

The result is a list of files in the /boot directory. These are the files that grub loads when the computer starts up. They consist of kernels and init ram disks. Notice in the listing we also see files that start with the text config-. These are the configuration files used to create that specific kernel. Recall we ran the command uname -r to get the current running kernel version, run that command again

uname -r

Notice there is a config- file with the same information appended to the end of it. We will copy this config file to the kernel source tree and call it .config. We will do this with the following command.

cp /boot/config-"$(uname -r)" ./.config

To recap, the cp command means to copy, some source file to a destination. The next part says in the boot directory the file config-(plus what our uname command prints out) will be copied to ./.config. The first ./ means the current directory and the file we are coping to will be named .config.

Configure the Kernel

Now that we have a basic kernel configuration copied over we can start in earnest. But first we need to set a couple of options in the kernel configuration ourselves. To do this we need to run the kernel’s menuconfig program. To do this we will run the following command.

make menuconfig

You can think of the kernel as the operating system for most intents and purposes. The kernel handles all of the interaction between you the user and the computers hardware. Todays kernels can handle a huge variety of hardware and file systems and much more. The menuconfig program allows you to select what the kernel will have built in, excluded or what you might want to use loadable modules for. In our case, we want to tell the config program that we want to build a fully preemptible kernel.

When the menuconfig has been created the first thing we want to do is to load the configuration that we copied over. To do this we will use the right arrow key and arrow to the load menu entry and press the enter key. It asks for the name of the configuration file we want to load. Recall we copied the file over and named it .config. This is what is populated in the dialog by default, so we can just press the enter key to load it.

First, we will make sure that the kernel is set up to be a fully preemptible kernel. To to this, we will arrow down to General setup ---> in the main menu and press the enter key. Now that we are in the General Setup menu, arrow down until Preemption model is highlighted and press the enter key. Here we will be given a dialog with the list of different preemption models. Arrow to highlight the selection that reads Fully Preemptible Kernel (RT) and press the enter key to select it. You will be placed back in the General Setup menu and will notice that our selection is printed on the same line as the Preemption model menu line. With that completed, arrow right to exit and press enter to leave the General Setup menu.

Next in the list of main menu items is the 64-bit kernel option. This depends on you and the system you are running. But in my experience, unless the system has more the 4 gig of ram and or you are working with HUGE data, then I always install the 32-bit distributions of Linux. So in my case I make sure it is turn off by pressing the N key. If the option is turned off and you want to build a 64-bit kernel, then press the Y key to turn the option on. It will be denoted with an asterisk if it is on, and empty brackets if it is off.

Finally, as I understand it ACPI can interfere with realtime systems. You may want to turn this feature off. To do so, arrow down to the Power management and ACPI options and press the enter key to open the sub menu. Next arrow down to the ACPI menu entry. The N key will turn this option off and the Y key will turn it on. Press whichever you want, but I have elected to turn this off. Now, to get back to the main menu arrow right to exit and press enter.

This will be all the changes that I will make in this tutorial for kernel configurations. Feel free to explore the other menu entries and if you are curious of what they do, you can highlight an entry and then right arrow to help to read about what that function does. I strongly encourage you to be careful of what you do with the kernel config. You can make an inoperable kernel and thus a system that will not boot.

Once we are done with the kernel configuration we want to save that config for the compiler to use when we build the kernel. From the main menu, arrow right to save and press enter. A dialog will open and ask you for a name for the config file. By default it will be .config so just press the enter key to save the file. It will then inform you that the config file has been written and you can press the enter key again to exit this dialog.

We are done with the kernel configuration and can leave the configuration tool. To do this, arrow right to exit and press enter.

Compile the Kernel and Modules

Now that the configuration is complete we can compile the kernel and the modules. We do this by issuing the command make or make all. In your terminal window type make and press enter.


Now this part will take quite some time. It all really depends on your system. While testing on a virtual machine, my computer too a little over 2 hours to compile the kernel using a single processor. Yours may be faster or slower, depending on your processor and memory. If you have more than a single core processor you can run make with the -j flag and tell it the number of cores to use. If you are unsure how many cores you have, you can issue the following command:


It will print a number indocating how many processor cores the computer has. In my case the computer has two cpu cores. To compile the kernel using both cores issue the following command:

make -j2

Now, go get some lunch, coffee or something while the compiler does its thing. And come back here when it is done.

Install the modules

Now that the computer has finished compiling the kernel and modules we can install the modules. This needs to be done with elevated permissions because we are copying them to an area that belongs to the system. To install the module, enter the following command:

sudo make modules_install

This will take a few minutes as there are many modules to copy over. When this is complete we can install our newly built kernel.

Installing the kernel

Last thing to do is install the kernel. Again, this requires elevated permission. To do this we issue the following command in the terminal:

sudo make install

This command does quite a bit of work, it copies the config file, system map and kernel to the systems /boot directory. It will create and copy over the initrd file and then finally make a call to grub to install it as a menu entry in the boot loader. It only takes a few minutes to complete.

Booting the new Kernel and verifying that it loaded

Now that we have installed the new Kernel, we need to boot the computer using it. To do this, close all the windows and do a logout / reboot or enter the following command in the terminal:

sudo reboot

When Grub loads up we can select the first entry or just let it run. When the computer finally boots up, open a terminal and type the following commands

uname -r

The text outputted will be the kernel version that is running in memory. In the case of this tutorial it will read


If you run the command:

uname -a

You should see the words PREEMPT RT somewhere in the listing indicating it is a realtime kernel.


Congratulations!!! Now you have a system that runs a realtime kernel. Now we can compile LinuxCNC to run on it. That is another tutorial though.

End of Tutorial - Last Revision [06 MAY 2019 – 16:07]

LinuxCNC Tutorial 1 – Good Wiring Practice

Written by Joe Hildreth – http://www.myheap.com

When I built my first CNC machine, I didn't have a cabinet and really ran nothing more than the stepper motor controllers and power to the parallel port break out board (BOB). Later I added a touch off plate to make setting up the tool to the surface of my material easier. Wires were all over the place, components mounted to a board and away I went.

When I built my second machine, I thought I would do a neater job of things and I made a metal drawer that would slide into a computer rack and mounted all my components to it. I carefully bundled all the wires together. I even used zip tie squares to hold the wiring to the enclosure. It sure was “purdey”!

Then I decided, I would make a series of tutorials on how to locate an input pin, write the G-Code and everything else related to setting up a touch off plate for the new guys and gals out there trying to figure all this stuff out. It was during this exercise that I learned my neat and pretty wiring job was not conducive to a properly operating CNC Machine. I discovered this when I was trying to run a G38.2 linear probe command and it would stop and some random position along the way. I would restart it and it would stop again. I had to run the commands several times before the probe command would finally complete. I knew that something wasn't right, so I made a video and posted the question to the LinuxCNC forums. Within a few hours, a couple of folks on the forum had given me enough information to understand what was going on. A HUGE thank you goes to ArcEye and Andy Pugh for all the advice and suggestions they gave me. The culprit it seemed was noise.

So what is noise. Electrical noise comes from a couple of things. First is EMI (Electromagnetic Interference) caused by current flowing through wires and the second is electrical mechanical noise cause by physical switches bouncing when they open or close. Both of these conditions can cause you problems with the daily operation of your CNC machine. The mechanical noise can be dealt with pretty easily, but the EMI noise on the other hand requires a little work to help reduce and prevent it. The guidelines that follow are some things that you can do to reduce this problem. Before we get to the list of things to do, let's first discuss a little more what EMI is.

EMI as I stated above is caused by current running through a wire, but there is a little more to it. When current runs through a wire a magnetic field is created. As the current builds the magnetic field gets stronger. Then when the current ceases to flow through the wire the magnetic field collapses. This in itself isn't too bad, but if this magnetic field happens to cross another wire it will induce a voltage across it. This is how a transformer works. It uses a magnetic field in one coil of wire to induce a voltage in another coil of wire. If a wire is able to induce a voltage across another wire that we are using for a signal at logic level voltages, it may drive the voltage level in that wire to some state that the logic circuits reading it cannot understand. To be clear, 5V TTL work on distinctive voltage ranges. An input voltage of 0V to .8V is considered a false or low logic level. A voltage level of about 2V to 5V is read as a true or high level input. If however a voltage somewhere in between the .8V and 2V is on the input then we do not know what the output will be. When an input in this range is given the output could be either a high or a low level and this has to be avoided for a reliable circuit. Knowing the above information we know that a magnetic field crossing our signal wires could drive the input voltage to a TTL circuit into this band resulting in unexpected operation. But this is only half the story.

When current is switched on and off in a circuit we know that it creates a magnetic field but when current is switched on and off repeatedly it is possible to create another kind of noise. If the rate the current is being switched on and off is fast enough, it can generate radio frequencies that can interfere with other equipment nearby. The strength of these radio frequencies again depends on the amount of current that flows through the wire.

Now that we know what EMI is and the effects that it can have let's discuss what we can do about it by giving some general wiring tips.

AC Line Voltage

The AC that you use can inject noise into your power supplies and other equipment. If you have motors running on the same circuit for example, can create noise on the line if it is running on the same circuit as your CNC components. RF signals can also be superimposed onto AC line voltage. Years ago, this fact was exploited in some home entertainment systems to provide music to a remote speaker over the AC line. In-line filters are made to attenuate (reduce or block) this type of noise from the AC line voltage before it is run into your equipment. AC Line Filters can be found at electronic supply houses. LinuxCNC forum user “lead_injection” recommends Medical Grade filters as they have the lowest leakage current.

PSU's (Power Supply Units)

  1. AC Grounds

    A typical CNC machine may have a few different power supplies installed and in use on the system. Make sure the AC inputs to your power supplies are properly grounded. Tie them all to the same ground. Many power supplies have a metal case and the case is usually tied to the AC ground as well so keep this in mind when you are fastening them down. In my case I have a metal drawer that I am using, so when I fasten down the power supplies, I need to keep in mind that the AC ground will be attached to this drawer as well.

  2. DC Grounds

    There are two trains of thought when it comes to the DC ground. Some folks say that you should ground it to the AC ground and others suggest that you should create a separate isolated ground plane for the DC power. I don't know if one style is better than another but if you are interested a Google search you can find folks that will defend either side of the argument.

    Additionally, many suggest that you keep the ground for any supply providing logic level voltages segregated from any other DC supply to prevent ground loops which could create new additional problems. A ground loop exists when the grounds of two different devices are at different potentials. For example, if the PSU for your drivers were at a different potential than your supply for your logic and you tied them together, you could corrupt your logic signals by a small voltage change. If this difference in voltage is enough to push your signal into the unknown state we discussed above, then your equipment will be unreliable or possibly erratic.

    In my controller drawer I have three PSU's. Two of them are 36VDC and one is a 5VDC. The 36V supplies are meant to run my stepper controllers while the 5V supply will provide power to my BOB (Break Out Board) and TTL signal level voltages. My intention is to give the 36V their own ground plane and to isolate the 5V supply for the logic.

Stepper Motor Controllers

When wiring the controllers up, the following list should be helpful.

  1. The metal housing of the controller should be grounded. You can verify this with a multimeter set to check continuity. Best practice is to mount your controllers directly to your ground plane. The ground plane as you recall from above is an isolated piece of metal that you will attach the ground from your PSU that supplies your controllers. A simple way of doing this is to use a piece of aluminum plate for the ground plane and mount it to your enclosure using insulated standoffs. Mounting your controllers to this plane allows any noise the controller might generate to be diverted to ground rather than emitted through the air and possibly affecting surrounding equipment.

  2. The controllers that I have experience with have two sets of connectors. They are divided into two groups. The first group is power supply and motor leads. The second group are control signals. When wiring your controllers keep these two groups separated. Run your power and motor leads to one side of the controller and the signal wires to the other if at all possible. Again, using shielded wire will take you a long way in avoiding extraneous noise.

  3. DC Supply wires

    When running power to various pieces of equipment in your electronics box, using twisted pairs will aid in negating noise from neighboring wires. The twist in the wire creates a canceling effect on any magnetic field that passes across them. For additional protection use twisted wire that is housed in a shielded jacket. This type of wire typically has a metal foil or braid wrapped around the wire along with a stranded wire that runs beside it. The foil or braid will absorb the magnetic field that a neighboring wire produces as current runs through it. For best results, attach the stranded wire to the DC ground. Doing this will prevent the field from passing beyond the shielding to affect the wires contained in the cable. When grounding the shield wire, only ground at one end. Grounding the shield wire at both ends can create a loop that can effectively negate the ground allowing noise to be injected back into the wire.

When making power connections to the controller use a twisted pair of wires. You can twist them yourself, but make sure you have at least one twist per inch of wire. For best protection use a shielded twisted pair and attach one end of the shield wire to your grounding plane. The piece of aluminum plate your controllers are mounted to.

When making connections to the motors, use shielded cable. These wires carry the most current and will emit a lot of magnetic radiation. Be sure to ground the shield wire to the ground plane.

When making signal connections to the controller (The step and direction pins) use a twisted pair to make the connection. Category 5 Ethernet cable is cheap and contains four twisted pairs. This makes excellent signal wire. You can strip the housing back enough that you can run two pair to one controller and another two pair to a second controller. You can also buy Ethernet cable with a shield. If you ground this shield, be sure to ground it to the PSU that supplies your logic signals and not to the power plane for your stepper controller and its PSU.

Variable Frequency Drives (VFDs)

VFDs are used to drive spindles and work by varying the frequency of the AC going to the spindle. VFDs are great noise producers. If at all possible locate your VFD in a separate enclosure or cabinet to reduce the risk of it injecting noise into your other wiring. Recommended wiring for the VFD is foil braid or copper tape shielded wire and observing good grounding practices. A PDF document from Belden on the topic can be found at the following URL.


Wire Selection and Use

Wire comes in many types, sizes and configurations. Wading through all the wire available is a monumental task of its own, but for our purposes we only have a look at the types of wires suitable for wiring a CNC controller. Additionally, how the wire is to be used can have some affect on the overall system. What follows are some tips that may prove helpful.

1. Shielded Wire.

There are basically three types of shielded wire. One has a bare wire braid that surrounds the wire inside, and the other has metal foil that surrounds the wire inside. And lastly, there is both a braid and metal foil. All of these are designed to prevent noise from being injected into the wire enclosed. The type of shielded wire you will select will depend on the amount of noise you are trying to combat. A brief discussion of each follows.

A) Foil Shielded Wire

Foil shielded wire has a thin metal aluminum foil that is usually bonded to a film of plastic that surrounds the wire. The enclosed wire is usually 100% covered and that is good. Foil shielded wire can be difficult to use, especially when trying to attach a connector to the shielding in order to ground it. For this reason, you will usually find a bare metal stranded wire enclosed that you can make a connection to. Of the three types of shielded wire, this is the least effective.

B) Braided Shielded Wire

Braided Shielded Wire has a metal braid that surrounds the wire. It is more bulky than the foil shielded wire and does not provide 100% coverage. It typically covers 70 to 95% covering depending on how tight the braid is made. The braid is typically made of tinned copper wire. Because copper is a better conductor than aluminum and it's bulky size it works better to shield the wire than the foil shielded wire. It should be noted that this type of shielded wire will cost more than the foil shielded wire above. Of the three types this one is more effective than foil shielded wire, but less effective than the next one discussed.

C) Multi Shielded Wire

For very noisy environments a wire that contains both foil wrapped wire and a braid will provide the most protection. As you can guess, of the three types this is the most expensive.

2. Routing Wire

There are two types of routed wire. Wire that is stationary and wire that gets moved as the machine runs. Along with this, we must consider the effects of neighboring wires to the wire being routed may have. The following recommendations were given by forum member lead_injection.

A) Routing Movable Wires

Any wire that will be moved about in normal operation of the CNC falls into this category. For example, the wires that run from your controllers through cable management and then to your motors.

If you are flexing your cables, use high flex rated cable (IGUS). This may get pricey for 4pair STP (Shielded Twisted Pair) type cables.

If running cables in a cabletrack/carrier tie them down at both ends of the cable track. If not, ratcheting can occur and fatigue the cable prematurely.

In a cabletrack/carrier observe the neutral axis idea. Have the wire run as close to the neutral axis as possible. Make sure the wire is not in tension in the longest neutral axis situation.

B) Routing Stationary Wires

Running different signal classes (high voltage and low voltage) in metal conduit may make the noise worse. Separate by as much distance as possible and if they have to cross, cross them at 90 degree angles.

Avoid wiring loops coming off of devices - they are great antennas for receiving noise, or great antennas for transmitting noise. Run wires along the ground plane.

Signal Wires

The wires that are used to transmit logic signals are the most susceptible to noise interference. The reason for this is the low level voltages that are used to convey the information. The following will prove helpful in keeping your signal wires clean.

1. Isolate the PSU for your signal wires from the rest of the system. Keeping the power supply isolated will prevent your other supplies from interfering with it.

2. Use twisted pairs to carry your signals. For best results use both wires and do not share a common ground for two or more signals. Use a pair of wires for each signal. Using shielded wire is best. When grounding the shield wire, ground to the logic PSU.

3. Shielded Twisted Pairs (STP) are most beneficial to differential signals. If you add the noise to both signals, the common point is not affected - the magnitude of the difference is maintained.

Stranded Wire

Wire comes in two forms, solid conductor and stranded. Both have their ups and downs. Stranded wire is pretty common in cables because it is more flexible. When using any stranded wire keep the following things in mind.

1. Terminate the ends

Little wires hanging off the end of your cable can create problems. They can cause shorts when wired next to other wires in close proximity or to the boards they are connected to. They can also act like a little antenna that will help them emit any noise they may be trying to generate. There are several ways that you can terminate them.

A) Twist and solder the ends. Tinning the wires in this manner makes then easier to insert in the set screw connectors and binds all the little wires together preventing them from fraying apart.

B) Use crimp on ends. Crimp on ends like spade connectors or bootlace ferrules also work very well. It is best to not to tin the end before crimping them. Tinning the wires could allow them to loosen over time. Attention to detail and the proper selection of the crimped end will form a quality mechanical connection.

2. Be careful of the amount of insulation you strip from the wire. Stripping too much insulation off will lead to exposed wire that something can short against. If you do simply trim off the extra wire.

Control Signals

When a limit or home switch is engaged, or a probe has made or broken contact, we use this signal to signify the event has taken place. Typically this is done by using input pins on the parallel port. The signal voltages used on the port are in the 3 to 5 volt range depending on the type of port you have. It only takes a small noise injected onto the signal wires to put it in that unknown voltage area we discussed above, resulting in an unknown TTL state. If after careful wiring and planning you are still having these kind of issues, there are a couple of things you can do to fix the problem.

1. Higher control voltages. If instead of using the logic PSU to supply the voltage for the detection circuit you used a larger PSU, for example a 12 or 24V supply to the input side of a mechanical relay or SSR (solid state relay), the control circuit would be less affected by noise. In turn, the mechanical relay or SSR would turn on or off the control signal to your parallel port or breakout board allowing you to keep these small control voltages in short runs and contained in your wiring cabinet. In addition you may be able to find opto-isolators or opto-couplers that will work on higher input voltages that will switch the lower TTL voltages to the port. A search on Jameco, Mouser or other electronics supplier should turn something up.

2. Higher control current. If you are using pull up resistors on your inputs, you can use a smaller valued resistor to increase the current draw and reduce the chance of a false signal. Keep in mind the additional current load on your PSU. You can calculate the current load with a judicious application of Ohm's Law.

Mechanical Noise

Mechanical Noise happens when mechanical contacts open and close, as in a switch or relay contacts. As they open or close they will bounce against each other creating a rapid state change in the circuit. The electronics monitoring the change in state, the opening and closing of the contacts, can detect these quick changes. Sometimes it doesn't matter, but more often than not, you don't want this condition to interfere with the operation of your machine. For example, it will generate errors when probing. However, like I mentioned above, this situation is pretty easy to remedy.

1. Debouncing a switch with hardware.

Debouncing a switch can be done with the addition of some hardware to the signal circuit. There are ICs (Integrated Circuits) like Motorola's MC14490 that are designed to do just this thing, but they can be difficult to find. A simple method of debouncing a SPST switch uses an RC network (sometimes coupled with a diode to increase the speed) as a delay into a Schmitt triggered inverter allowing it to compensate for the time it takes the switch to settle down. If you are interested in this method, you can find more information on the subject by visiting the following URL:


Additionally a great video on debouncing a SPST switch can be found here:


I may at a later time create a tutorial on how these circuits are made, but there is an easier way. That comes next.

2. Debouncing a switch with HAL

The hardware abstraction layer (HAL) of LinuxCNC has a Debounce component. The Debounce component has a single input pin and a single output pin. Its job is to look at the input and to send the output after a programmed delay time. The Debounce HAL component will be covered in a separate tutorial when we create a touchoff plate for the CNC machine. More information can be found for the Debounce component by visiting the following URLs:



Documenting your wiring cannot be over stressed. With power feeds, motor leads, signal wire and everything else you stuffed into your your wiring compartment, you will be grateful that you documented your wiring. A year after you completed your CNC wiring and you want to add something, or some trouble arises, you will have your documentation to fall back on.

So, what should you document? The list that follows probably should be the minimum you hang onto and if you think you should note or save something else, you probably should.

1. Hardware Documentation.

At a minimum, make sure you save any documentation you have for your hardware in a safe place. Stepper controllers, Break out Boards, Power Supplies, PID controllers, individual components if they apply, Servo Controllers, etc. Although it takes a little more room, I print all the electronic documentation for the stuff I have and keep them in a binder in plastic sheet protectors. This binder is divided into sections based on the type of hardware or documentation I am keeping.

2. Wiring Schematics

As you wire your CNC, make sure to draw up a schematic that you can reference later. The schematic does not have to be all that neat, but you must be able to pick it up a year later and understand what you have done. Be sure to annotate your schematic with any additional information that will help remind you of what you made. Keep a copy of your schematics in your documentation folder so it does not get lost. If you keep things electronically, scan your schematics and save it with the rest of your documents. If you don't have a scanner, you can take a digital picture and save it to your computer.

3. Label your wires

Take the time to label your wires. When you start bundling wires, it is hard to look at them and know for sure what is what when you go back to modify or change something a year later. Label your motor wires with the joint or axis they run, label your signal wires so you know what they do. The idea here is to make it easy to identify a specific wire or set of wires you have in your controller.

Additional Information

1. LinuxCNC and Machine Related Questions

Additional Information and help can be found by using the LinuxCNC forums. If you are not a member of these forums, I encourage you to join. Please visit:


The folks there are very helpful, have loads of experience and are willing to share some insights.

2. Cable and Wire Harness Assemblies

Publication IPC/WHMA-A-620 covers the Requirements and Acceptance for Cable and Wire Harness Assemblies. This publication describes acceptability criteria for producing crimped, mechanically secured, or soldered interconnections and the associated lacing/restraining criteria associated with cable and harness assemblies. It is not the intent of this document to exclude any acceptable procedure used to make the electrical connection. A 2002 version of this document can be downloaded from the following URL.


3. Understanding EMC (Electromagnetic Compatibility) Phenomena

A publication from Groupe Schneider goes into depth about what Electromagnetic interference is and how to design your system with it in mind. This is a great document is you want to know the what and why of electromagnetic interference. It discusses in detail, cables, grounds, types of interference, chassis connections, filters and more. A very good source of information to those who want to know more on the topic. You can download a copy of the 200+ page PDF from the following URL:



I would like to thank the following people from the LinuxCNC forums for their input on this tutorial. It is with their help I am able to give you the information contained herein.

Andy Pugh
Clive S.
Peter Ommen

(End of Tutorial – Last Update 12 APR 2017)