Chapter 12 -  Mach 3  LinuxCNC

If you have this book, you know that Michael Simpson suggests the use of the Mach 3 controller software to run it.  Mach 3 is both stable and affordable and easy to get.  Again, as with the electronics of the machine I am going to take a bit of a different path for the controller.  Now, this change isn't a slight against Mach 3 or anything like that.  I just want to use LinuxCNC because I am used to it and have no experience with Mach 3.  Additionally, I like the openness of the LinuxCNC project and the almost infinite ways it can be used and configured.  Additionally, I want to provide more choice to the homebuilt CNC community who may be on a shoe string budget or just want to do something different.  This page is not intended to start a boxer -vs- briefs war, just a choice.


LinuxCNC is open source software and is free of charge.  While the creators of this controller software do their best to provide a robust, bug free platform to run your CNC machine, there is no guarantee that it will work for you.  Additionally, Open source software will require work on your part to configure and use.  LinuxCNC can be complicated and it is highly recommended that you read the Getting Started Guide and the User Manual.  This notice is not meant to scare or intimidate you, it is just a fact that the open source community expects you to do your part too.  That does not mean that help isn't available, there are a lot of people who use LinuxCNC who are willing to help you diagnose and use the software.  The best place to find information is the LinuxCNC website by viewing the documentation and visiting the Wiki and Forums.

Moving on ...

I have been using LinuxCNC since 2006 when I built my first CNC router.  With a little patience and work, I am sure it will be a good controller for the KRMx01 CNC Router as well.  I will attempt to document what I have done to install and configure the software to give the same functionality that Mr. Simpson provides with the Mach 3 software in his book.  Hopefully, with some feedback from you all we can put together a page or pages to make that happen.

I will be making a couple of assumptions before I start.  I am assuming that you will be using a dedicated PC for your CNC machine and that you will not be dual booting different operating systems and other stuff like that.  If you are the type who dual-boot operating systems on your computer, then your skill set will allow you to fill in the details not presented here to get the software installed.

Getting LinuxCNC

LinuxCNC is free and available for download from  When you go to the site, you actually have a lot of different choices on how to get the software installed.  You can for example, compile it your self, download a live CD, install it as a simulator, etcetera.  This guide will focus on installing LinuxCNC as a stand alone system from a Live CD ISO.  LinuxCNC 2.6 on Debian Wheezy is the newest live CD offered by the LinuxCNC community.  It installs LinuxCNC v2.6.1 and the XFCE desktop.  It is currently supported by Debian and will be for about a year after Debian Jessie is released.  Many folks do not like the light weight XFCE window manager, but this can be easily changed if you desire.

Getting it all installed

I have created a screen cast on how to download and install LinuxCNC on your computer.  You can watch it below.  If you have any questions, please email me using the contact us link from the menu above.

Updating LinuxCNC to the newest Version

I have created another video that will show you how to update your LinuxCNC install above to the most current release of LinuxCNC.  At the time of this writing it is 2.6.3.  Again, if you have any questions, please use the contact us link from above.

Running the Latency Test

The next thing to do is to run the latency test.  This test determines ultimately how fast your computer will be able to run the controller.  The video below shows this process and also gives some reasons why.

Gathering Data for configuring LinuxCNC

Now that we have LinuxCNC installed and at the most current version, we need now to collect some data so that LinuxCNC can be configured to run the machine.  We will need to collect the following information to set up a bare minimum configuration.  As time goes by and additions to the machine are made we will be adding other information to the data sheet or information sheet we put together.  When you create this document, it would be a good idea to keep it with your other documentation for the machine.  We will need the following data:

  • Results from the latency test above.
  • Stepper controller information for Step Time, Step Space, Direction Hold and Direction set up
  • Step and Direction pins for each of the four joints that make up the X, Y and Z axis.
  • Mechanical information about each axis on the machine.

Later we will be adding information like pins used for home and limit switches, pins for the probe, pins for the Super PID closed loop router control, etc.

Results of the latency test

If you have not done so yet, you will need to run the latency test from the CNC menu.  The latency test determines just how fast your computer can respond to a request.  If you look at section 5.3 of the Getting Started document, you will see that it describes the use of the latency test in detail, including how to trouble shoot some possible SMI latency related issues.  In a nutshell, you want to start the test and then abuse the computer as much as you can.  By abuse, it means run a bunch of programs, play a game, browse the Internet.  The idea is to try to work the machine hard to see what the worst case scenario is for the test.  Also, the longer the test the better.  Occasionally, something will pop up and cause you latency issues that would best be caught when you run the test for a long period of time.  I wouldn't hurt to run it over night.  When that is done we will add it to our list of configuration for safe keeping.

Configuration information for KRMx01 CNC Router for LinuxCNC
Latency Test 19732 ≈ (20 µs)

Stepper Controller Information

When you bought your stepper controller, it should have came with a data sheet giving you the timing specifications.  Some controller manufacturers give a great amount of information with their product, and others you are lucky to get the pin out diagrams.  The controllers I have are really somewhere in the middle bordering on the ladder.  The specification sheet for the CW230 stepper controller only tells me a couple of important details aside from what connections do what.  If you want to follow along here, you can get the specification sheet from the electronics page on the KRMx01 build log.  If you look at the sheet, you see the only timing information is the stepping pulse.  It reads that the stepping pulse is 5V, rising edge effective and must be greater than or equal to 10µs.  However, if you look at the opto-isolated diagram you see that the CP+ has to be wired to 5V and that the CP- will have to go low to activate the circuit.  Something is wrong here.  Assuming that the circuit is correct (Because I have run it this way) our signal then is active on the falling edge of the pulse when it drops low.  This will become more important later.  So for Step Time and Step Space I am going to use 15000 ns.  This is 10000 ns (10 µs) + another 5000 (5 µs) for any propagation delay.  I may be able to bump these values down, but these are safe and will get us up and running.  Finally, because the sheet does not give any specifications for the direction pin, we are going to use a save long value of 20000 ns (20 µs).  Updating our table we should have the following:

Configuration information for KRMx01 CNC Router for LinuxCNC
Latency Test 19732 ≈ (20 µs)
Step Time 15000 = (15 µs)
Step Space 15000 = (15 µs)
Direction Hold 20000 = (20 µs)
Direction Setup 20000 = (20 µs)

If you don't have the timing values for your driver, take a look at the LinuxCNC Wiki under Stepper Driver Timing.  There are several drivers listed there.  If that does not work, please email me or post a message to the LinuxCNC forums and someone will try to help you out.  For a explanation of Step Time, Step Space, Direction Hold and Direction set-up, see section 5.2 of the getting started guide.

Step and Direction Pins for the Axis Joints

The book for the KRMx01 suggests that you have a Y-Axis and an A-Axis and that they are slaved together.  Truthfully, there is only the Y-Axis and it has two motors running it.  These motors are really two joints driving the same axis.  That bears repeating.  These two motors are really two joints driving the same axis.  This is an important distinction to make.  Later, when we delve into kinematics we have to understand what is meant by a joint and an axis.  A joint moves something, like an axis or rotary table.  An axis is something referenced by g-code.  To make the distinction on the KRMx01, I will call the motors (joints), Y-Axis-Left and Y-Axis-Right.  The left and right as when viewed from the front of the machine.

When I laid out my electronics drawer I simply laid out the drivers all in a row, and connected the step and direction pins to each one in line.  The motor output of the drivers were soldered to the 4 pin microphone connectors attached to the plate in the back of my electronics drawer.  You can see this on the previous electronics page.  I did, however, want my axis to come out in a specific order in the back of the drawer.  I wanted the X, Y-Left, Y-Right and Z to come out of the box in that order from right to left as looking from the connectors.  So, I had to determine which pins were going to what controller and look to see if they were direction or step pins.  Remember I told you that the Step and Direction pins on the controller were active low?  Well I need to note that on the configuration sheet as well.  You will notice that I am only documenting the step pins as active low logic.  According to the specification sheet for the driver the direction pin (CW-) is high towards and low reverse.  When we drive the screw we may need to invert these to get the proper direction on the motor.  With this information ferreted out, I can fill in the chart below as follows:

Configuration information for KRMx01 CNC Router for LinuxCNC
Latency Test 19732 ns ≈ (20 µs)
Step Time 15000 ns = (15 µs)
Step Space 15000 ns = (15 µs)
Direction Hold 20000 ns = (20 µs)
Direction Setup 20000 ns = (20 µs)
X Step (Active Low) Break Out Board Pin 8
X Direction Break Out Board Pin 9
Y-Left Step (Active Low) Break Out Board Pin 4
Y-Left Direction Break Out Board Pin 5
Y-Right Step (Active Low) Break Out Board Pin 6
Y-Right Direction Break Out Board Pin 7
Z Step (Active Low) Break Out Board Pin 2
Z Direction Break Out Board Pin 3

That is all the electrical configuration we need to get started.  Now we need to fill in the gaps for the mechanical components of each axis of the machine.

Mechanical Information

Before we can configure LinuxCNC to run the machine, we have to gather a bit more information.  This information is the mechanical details of each axis.  This includes things like, the number of steps per revolution of the motor, the thread pitch of the screws, if there is any gearing, and if we are using micro-stepping on the controller.  For the KRMx01, if you have followed the plans, there is no gearing between the stepper motor and the screw as they are directly coupled.  So motor teeth and lead screw teeth will both be set to 1 indicating there is no ratio in the drive train between the motor and the screw.  The steps per revolution for the motors I am using is 200. (This is standard for most motors)  I am using 1/2 stepping or put another way, it takes 2 microsteps to make one full step on the motor.  Finally, the lead screws are 1/2-10 acme 5 start screws.  What this means is that there are 10 threads per inch of screw, and the screw has 5 threads.  two full turns of the screw will move the nut 1 inch, so 1 turn will move the nut .500 inch.  The thread pitch is .500 inch.  All axis are the same, so the information should look like the following:

AxisMotor Steps / Rev.Driver Micro StepsMotor TeethLeadscrew TeethLeadscrew PitchTurns / Inch
X 200 steps 2 steps 1 1 0.5 inch 2
Y 200 steps 2 steps 1 1 0.5 inch 2
Z 200 steps 2 steps 1 1 0.5 inch 2

We now have all the basic information we need to set up LinuxCNC with a basic configuration.  Later, when we add things like limit and home switches, a touch off probe and a PID to control the router we will be modifying this configuration and adding more to our notes.

Setting up LinuxCNC to run the KRMx01

With all the information gathered, we are ready to configure LinuxCNC to run the KRMx01 CNC Router.  The simplest way to do this is to run the stepconf program under the CNC menu.  Stepconf will take all the basic information about your machine and build the configuration files for you.  Later if you want to make changes you can either run stepconf again, loading your existing configuration (if your making simple changes) or you can edit the configuration files with a text editor (If you are doing more complicated stuff)  One gotcha that you need to be aware of using stepconf if if you have made any edits by hand to your configuration, then later load your configuration with the stepconf program, when it writes the data back to disk it will overwrite any changes you made.  Below is a video walking through the process of setting up the KRMx01 using the stepconf program.

The video below shows the motors connected to the drawer and being jogged through the LinuxCNC control software.  I also talk about motor direction and changing it in the controller. I want to apologize for the poor audio quality of the video.

 Parting thoughts

KRMx01 LinuxCNC Configured and Running. With the basic configuration done and out of the way we are ready to connect the motors to the machine.  One thing that I would like to mention here.  LinuxCNC can control a wide range of hardware and systems.  If you are building a machine with different stepper drivers, or using servos, a plasma cutter or just about anything you can imaging, there is a good chance LinuxCNC may be able to control it for you.  I encourage you to read the documentation, visit the forums and wiki.  It can be hard work but the end result is rewarding.  Additionally, upgrades to the machine will be done separately from the mail build, but I will document them.  I will most likely create a KRMx01 Upgrades section and put them under there.

See you in the next Chapter!!!