Click here to go back to Getting Started: Setting up my PC

*** If you will be using Mach3, you should be at this page instead:  Setting up the SmoothStepper with Mach3. ***

*** Only the ESS supports Mach4. The USS does NOT support Mach4, please read here for more details.***


Setting up the SmoothStepper and Mach4 Software



Getting Started: Setting up the SmoothStepper and Mach4.

Setup Instructions to Install Mach4 and the ESS Plugin

ESS Plugin Configuration


Mach4 Core Configuration

Setup Instructions to Install Mach4 and ESS Plugin

Setup Instructions to Install Mach4 and ESS Plugin

For Mach4, we recommend using the ESS plugin build 220 found in step#3 of the Setup Instructions (below).  (Pictures on this page may show older plugin version numbers back to ESS plugin build 206, but that will not affect the setup process, since the config screens have remained unchanged from a functional standpoint.) 

Known issues (the status of software development is discussed here):

  1. THC is the current developmental priority.
  2. Homing only backs off the switch.  A lua script is required to then move a specified offset distance, and a video that shows you how to do that is here. 
  3. Lathe/threading support via G32/G76 was implemented in Build 213.  We are addressing the issue where successive threading passes do not start at the same rotational position.  CSS (Constant Surface Speed) is handled by Mach4 and is functional.


SETUP Step 1 - Run the SCU:

Confirm that you have used the SCU to prepare your PC for the ESS.   Please make sure that your ESS is powered and connected to your PC via Ethernet cable.   

Here is a video showing how to use the SCU (System Configuration Utility).


Here is a video showing how to install Mach4 and the ESS Plugin in SETUP steps 2 and 3.


SETUP Step 2 - Install Mach4 and its Documentation:

We recommend that you use Mach4 release version or newer.

Hobby vs Industrial:  There are two version of Mach4; Hobby and Industrial.  Most users will do well with Hobby.  Industrial has a few more advanced features and support (please view Mach's documentation to make your decision).  When you download Mach4, pay attention to if you are downloading the Hobby or the Industrial version.

    • Recommended: Here is the official current release of Mach4. (We don't test all possible CNC functionality against every new release, but main releases are typically functional for most users.)
    • Optional for advanced testers: Here is a link to the Mach4 FTP download page, where they have newer development releases.  (We don't test against most development releases, so they may have hew features and fixes or they may introduce new bugs and break functionality.) 

Mach4 provides a bunch of documentation on how to use Mach4, which you really need to read and understand.  You can find it in the Docs folder inside your Mach4 installation folder, typically C:\Mach4Hobby\Docs\

Mach4 Documentation


SETUP Step 3 - Install the ESS Plugin:

Use the latest recommended ESS Mach4 Plugin, build 220. Backlash Compensation and Spindle PID are now available.

  • For a new install: Place the plugin’s ‘.m4pw’ and ‘.sig’ files into your plugins folder, which is typically: ‘C:\Mach4Hobby\Plugins\’  
  • For an upgrade from a previous plugin version: This plugin should be fully compatible with profiles made in version 184 or newer.   First, make a backup copy of your entire Mach4 folder.  Then replace the plugin’s ‘.m4pw’ and ‘.sig’ files in your plugins folder, which is typically: ‘C:\Mach4Hobby\Plugins\’ The upgrade is complete.
  • Here is where the Beta Releases are posted, if you want to try a newer test releases as we make them. 
  • See the Change Log here.
  • While we list the older versions of the plugins, we only recommend that you use the most recent version.  Previous ESS plugin releases for Mach4:


SETUP Step 4 - Turn on the ESS:

Make sure that your ESS is powered and connected to your PC via Ethernet cable.

Here is a video showing how to Create and Configure a Mach4 profile as shown in SETUP steps 5 through 14.


SETUP Step 5 - Start Mach4:

Run Mach4 GUI or double click on the Desktop icon.


SETUP Step 6 - Select your Profile (if it exists):

For the "Select Profile" window, if you have already created a profile, select it and then skip to the ESS Plugin Configuration section.  If you have not yet created a profile, continue with the next step.


SETUP Step 7 - Create a New Profile:

To create a new profile from scratch, open Mach4 and click on "Create Profile".

Select Profile

  • Enter your new profile name, I used "My System", you may use any name appropriate for you.

 Profile Name


  • Click on the '...' and then choose "wx4.set" or another screenset that suits your needs; Press 'OK'.  You may change screensets at anytime inside Mach4 by clicking on Menu -> View -> Load Screen.

 Profile Name


  • Select your new profile, and press 'OK'

Select New Profile and press Okay


SETUP Step 8 - Enter the ESS's IP Address:

When prompted, enter in the IP address of your ESS.  The factory default IP is “” unless you modified it with the configurator. Press 'OK' IP Address


SETUP Step 9 - Select Motion Device Cancel:

When the Select Motion Device window appears, you will only be able to click Cancel.  Press 'Cancel'

Select Motion Device


SETUP Step 10 - Enable the ESS Plugin:

Go to Menu -> Configure -> Control... (used to be Mach…) -> Plugins tab:  Make sure that the “ESS – Warp9 Tech Design, Inc” plugin is enabled with a green check.   You will need to restart Mach4 if you change it to a green check.

Please note - If you will be writing or running lua scripts (like any macro above M99) you will need to enable LUA.  If you are enabling lua, you should also enable Regfile at the same time.   It does not hurt to enable these two plugins, so we recommend that you just enable them right now too.

Menu -> Configure -> Mach....

Enable ESS Plugin



SETUP Step 11 - Select Motion Device Cancel, Again:

When the Select Motion Device window appears, again, you will only be able to click Cancel.  The ESS will not be visible since the ESS plugin will not be enabled until after Mach4 restarts.  Press 'Cancel'

Select Motion Device



SETUP Step 12 - Restart Mach4 and Select Profile:

Exit Mach4, and then open Mach4 again, selecting your new profile

Select New Profile and press Okay


SETUP Step 13 - Select Motion Device -> ESS:

When the Select Motion Device window appears, again, you will finally be able to select the ESS as your Motion Device. Press 'OK'

Select Motion Device


SETUP Step 14 - ESS Communications:

Check for connectivity by going to Menu -> Diagnostic-> and click on the “ESS v***– Warp9 Tech Design, Inc” to see the Diagnostic Window.Menu -> Diagnostic -> ESS

Diagnostic Window


You should be able to see the Sequence ID and Device Time incrementing when the ESS is communicating with Mach4.


If nothing happens when you are in the diagnostic window, or you get messages that Mach4 can't communicate with the ESS, here are the usual problems: 

  • The ESS plugin was not enabled in step 10 followed by a Mach4 restart, and selection as the Motion Controller.
  • The ESS is not powered and connected to the PC.
  • There is a Firewall rule blocking communications with the ESS.


Please continue with the next section: ESS Plugin Configuration, below.



ESS Plugin Configuration:

These pictures were taken with ESS plugin build (version) 206, but will be valid for newer versions of the ESS plugin as well.  Please make sure that you have completed the previous section's Initial Mach4 and ESS plugin setup before you start this section.



ESS Entering the Config:

Go to Menu -> Configure -> Plugins… -> ESS v... - Warp9 Tech Design, Inc

Menu -> Configure -> Mach....


ESS Step 1 - Info Tab:

 The “Info” tab tells you the order you should follow while configuring the settings for the ESS.

Info Tab


ESS Step 2 - General Tab:

 On the “General” tab, you can:

1) Verify the IP address

2) Buffer Size (Almost always left at 0.18) :

    • A smaller buffer size is more responsive to Feed Hold commands and Feed Rate Override, but more sensitive to the ESS running out of data if your computer gets bogged down.
    • A larger buffer size (which translates to "longer"), is less likely to experience the ESS running out of data (in case Windows ignores Mach or the plugin for a while), but will take longer to respond to Feed Hold commands.

      The buffer size should be small enough that you have good response to jog commands, feed hold, and feed rate override.  I would start out small, and continue to increase it until the delay is noticeable and uncomfortable.  Then back off to where it feels good.

3) Set the Plugin Frequency; 40 Hz is the recommended value.

4) Monitor the Velocity FIFO Buffer - keep checked.

imgGeneral Tab


ESS Step 3 - Motors Tab:

On the “Motors” tab, you can:

  • Set your motors to work in Step/Dir mode, Quadrature Mode, or CW/CCW mode.  These motors will be assigned to your X, Y, Z, A, B and C axes in the 'Pins Config', 'Output Signals' tab, 'Mach Config -> Motors' window and 'Mach Config Axis Mapping' window. 
  • Note: While you can assign any axis letter to any motor number (0 through 5) and have it work correctly in Mach4, we discourage it.  Why?  Because most people will assume X =0, Y = 1, Z = 2, A = 3, B = 4, and C = 5.  Following this as closely as possible, will keep your system in line with most other systems, especially those that ran Mach3 previously.

Note:  The settings in this image are for illustration and you will want to use the values appropriate for your system.

 Motors Tab


ESS Step 4 - Spindle Tab:

On the “Spindle” tab, you can chose which mode to run your Spindle in.  Relay Mode and PWM mode are the most common choices.

  • In Relay Mode, you will have On/Off control of your router or spindle, and will not be able to adjust its speed from within Mach.  Assign the Spindle output signals for Spindle on and Spindle Forwards or Spindle Reverse relays.


Note:  The settings in this image are for illustration and you will want to use the values appropriate for your system.

 Spindle Tab


  • In PWM (pulse width modulation) Mode, you control the direction of your Spindle using M3 (clockwise) or M4 (counterclockwise). The duty cycle of the signal will be between 0% and 100% and your spindle speed control module will convert the PWM signal into an analog voltage (typically 0v to 10 V DC) that is used by your VFD to control the desired RPMs for your spindle.  You will need to set your desired base frequency (while we use a default  of 1 kHz, yours could be 25 Hz, 300 Hz or many other possible values).  To complete this portion of the spindle setup, please continue with step 25 below.


Note:  The settings in this image are for illustration and you will want to use the values appropriate for your system.

 Spindle Tab


  • In OB Mode you will be able to make your spindle run as Step/Dir, CW/CCW (clockwise / counterclockwise) or Quadrature Mode. To complete this portion of the spindle setup, please set it up as an OB motor, click here.

Note:  The settings in this image are for illustration and you will want to use the values appropriate for your system.

 Spindle Tab



ESS Step 5 - Pins Config Tab:

On the “Pins Config” tab, you can:

  • For Port 2 and Port 3 you may choose to have Pins 2 through 9 be either inputs or outputs, as needed for your system. When you change this, these modified pins will have their signal assignments (or pin assignments) deleted from the 'Input Signals', 'Output Signals' and 'Homing' tabs.

Port 2 and Port 3 Pin Direction


  • If a pin is to have its logic level inverted, you MUST do it here in the ESS's Pins Config.   Do not invert a pin's logic level in the Mach Config! That will just cause problems.

Active Low or High


  • While not mandatory, we strongly recommend that you assign an Alias name for each pin you wish to use, since Alias names make it MUCH easier to troubleshoot.  Each Alias must be unique.  


  • Here is a suggested naming convention that will help to make it VERY obvious as to which type of signal you are dealing with while setting up your profile.  This is optional, but it will help to catch and prevent mistakes!
    • Use a ‘MOTOR N’ prefix for motor Step, Direction, Quadrature and CW/CCW signals going out.



    • Use ‘SPINDLE’ for spindle PWM, Step, Direction, Quadrature and CW/CCW signals going out.



    • Use ‘ENABLE’ for enable signals going out.



    • Use ‘IN ’ for input signals.



    • Use ‘OUT ’ for the remaining output signals.



  • CAUTION:  If you rename an Alias in Pins Config, it will update the name on the 'Input Signals' and 'Output Signals' tabs.  This may result in a signal going to an unintended output, or being read from an unintended input!


  • If a pin is an input, you may perform noise filtering.  However, you really should address the noise issues inherent in your wiring and electronics by fixing the noise at its source, because noise filtering only masks the problem and delays the signal.
    • The minimum value is 0.0 (no filtering), the signal goes straight through.
    • The step size is 1.85 us.
    • It will round up to the next value.  i.e. 0.01 goes to 1.85 us.   2.0 goes to 3.7 us.
    • The Maximum size is 120,000 us (0.12 seconds)
  • If you need to use noise filtering as a stop-gap measure, here would be some reasonable values:
    • 1000 us on home and limit switches
    • Preferably no filtering on EStop or Probe signals
    • NEVER USE filtering on index or encoder signals; it will cause data loss as you increase to full speed!

Here is an example Pins Config window.  YOURS WILL BE DIFFERENT!

Pins Config Tab



ESS Step 6 - Input Signals Tab:

Here is a link to the description of all the available Input Signals.  On the “Input Signals” tab, you can:

    • Enable any input signal you wish, by placing a Green check in the Enable column. Then assign a pin alias (or Port M Pin N pin) to the Mapped Pin column, which you created in the Pins Config tab. 

Enable Input Signal


    • If you want to clear a mapping, select the blank line at the top of the drop down box, otherwise, select one of the available input signals.

Clear Mapping


    • You may use a single input pin’s alias for multiple mappings.  Just select from the drop down list in each cell of the Mapped Pins column.

Multiple Mappings


 Here is an example Input Signals window.  YOURS WILL BE DIFFERENT!

Input Signals



ESS Step 7 - Output Signals Tab:

Here is a link to the description of all the available Output Signals.  On the “Output Signals” tab, you can:

  • Enable any output signals (left most column) you wish, by changing the Enabled column to a green check mark.

Enabled Outputs

  • Assign an enabled output signal to one or more Output Pins (or Aliases you set up in the Pins Config tab).
  • An Output pin (alias) may only be assigned to one signal in the Output Signals Window.
  • There are 3 columns, so a single output signal may drive one, two or three output pins (aliases).
  • A few BOBs will require a Motor N Enable signal or a Charge Pump signal to function properly.


 Here is an example Output Signals window.  YOURS WILL BE DIFFERENT!

Output Signals


ESS Step 8 - Homing Tab:

  • The plugin will automatically populate the Home Pins for you, based upon the settings in the Input Signals tab.
  • Motors that have a “Home Pin” listed will be homed when you do a Ref All Home or reference that individual axis. 
  • ONLY check 'Enable Homing To Motor Index' if you are using encoders or a rotational axis that has an index pin. 
  • The plugin will automatically populate the 'Index Pins' for you, based upon the settings in the Input Signals tab.
  • You may change the 'Approach Velocity' to speed up or slow down how fast the system approaches the homing switch.
  • You may change the 'Backoff Velocity' to speed up or slow down how fast the system leaves the homing switch.
  • Mach4's homing speed percentages are ignored by the ESS plugin, since we require 'Approach Velocity' and 'Backoff Velocity' fields.
  • In step #21 (below), we will configure those settings inside Mach4's 'Homing and Soft Limits' tab.


      Here is an example Homing window.  YOURS WILL BE DIFFERENT!

    Homing Tab


ESS Step 9 - Probing Tab:


  Here is an example Probing window.  YOURS WILL BE DIFFERENT!

Probing Tab




ESS Step 10 - ESS Config Completed:

You are finished with the ESS Plugin Config. Please close the ESS Configuration window by pressing 'OK' at the bottom of the window.




Mach4 Configuration:

Here is the current Mach4 Installation Manual (MIM), which details what all of the fields and settings are.   There are other manuals provided for you in your "C:\Mach4Hobby\Docs\" folder. Please read them since they provide lots of useful information!

This guide will only cover the fields that are the most relevant to getting Mach4 and your system running with an ESS.  The Mach4 documentation will cover the remaining fields for you.


Mach Entering the Config:

Go to Menu -> Configure -> Control... (used to be Mach…)    As we look though the Mach Config tabs, you will see that quite a bit of this has been filled in for you automatically!

Menu -> Configure -> Mach....


Mach4 Step 1 - General Tab:

 Mach's General Config tab, has some settings you need to pay attention to:

    • Units.  You will need to choose Inches or Metric, and it is best to choose the same units for both the Machine Setup Units and your Units Mode.  I will use Inches since that is what we use in the US.



    • Control Mode will allow you to choose between: Mill, Lathe, Tangential and 3D Printer.

Mach Control Modes


  • The rest of these settings will suffice for most users to get started.  Please read the Mach4 Installation Manual (linked above) for more information on these settings.

  Mach General Config



Mach4 Step 2 - Axis Mapping Tab:

We will skip the Motors tab and cover the Axis Mapping and Homing tabs first.

Please refer back to your ESS Output Signals tab to see which motors you are using, and how they are setup.

Mach's Axis Mapping tab.  This allows you to specify which Motors maps to which Axes.  In this example, I have Motor3 (which would have been my A axis in Mach3) slaved to my Y axis.

  • Assign your motors to the appropriate axes, and place a green check in the Enabled column for those rows.
  • Do not enable rows that you are not using.

 Mach Axis Mapping


Mach4 Step 3 - Homing/SoftLimits Tab:

We will skip the Motors tab and cover the Axis Mapping and Homing tabs first. 

Mach's Homing and Soft Limits tab.  This is where we set up our system to return to the home position for each axis.  You need to set up each axis individually.  Slaved axes will be handled automatically via the ESS and Mach4, based on the Axis Mapping tab.

  • Home Direction: Pos for homing in the positive direction.  Neg for homing in the negative direction.  (MIM p. 17)
  • Home Order:  A value of 0 means an axis will be skipped.  1 will be the first axis homed, 2 the next axis homed, etc...
  • Home Offset:  The home offset allows for a shift from the home switch position. This can be used to shift the home position if your home switch is not located at the end of travel. (MIM p. 17)
  • Home Speed %: This is ignored by the SmoothStepper.  To adjust the approach and back off velocities, please go to the ESS Homing Tab.
  • Home in Place:  This will home (zero) the axis wherever it is currently sitting, instead of using a home switch.  You would want to move the Home in Place axis (axes) to wherever you want them before you home.  Place a Green check mark if you want to enable this feature for that axis. ANY AXIS THAT YOU ARE NOT USING SHOULD HAVE A GREEN CHECK FOR HOME IN PLACE!  If you don't the ESS plugin may issue warnings about it in pop up messages.
  • Soft Enable is enabled with a Green check. If it is enabled, Mach4 checks the axis position against the upper and lower soft limit values and the axis will decelerate to the Soft Max or Soft Min limit when jogging and will prevent any incremental jogs past the limits. When running G-Code, any moves panned past the limits will not be done and the machine will be put into a stop condition and a soft limit error will be displayed. (MIM p. 18)


Please refer back to your ESS Output Signals tab and the Mach Axis Mapping tab in the previous step to see which Axes you are using, and how they are setup. 

If you have a home switch on an axis, you can have that axis assigned a home order.  If  an axis does not have a home switch, it should home in place.  In either case, that axis may have soft limits enabled.  Soft limits typically are placed just inside the working area in a way that the home or limit switches will not be activated.

In this example, I have it set up to home axes in the following order, Z(1), X(2), Y and its slave(3). All other axes had their home order set to 0 and were set to Home in Place.

Mach Homing and Soft Limits


Mach4 Step 4 - Motors Tab:

Now that we have done the Axis Mapping and Homing tabs first, we will now cover the Motors tab .

Mach's Motor Config tab.  For each motor on your system, enter the following (you will know this already or your parts providers can supply you with this information):

  • Counts Per Unit (this was steps per unit in Mach3).
  • Velocity in Units/Minute
  • Acceleration in Units/(Sec*Sec)
  • Backlash (if applicable)
  • Reverse (if applicable)
  • and Enable Delay (if applicable)

You only need to configure the motors you are using; you may ignore and uncheck unused motors.

How do you calculate your steps per unit?  Try this Excel spreadsheet made by RICH.  Or our cached version of it here.  We do not guarantee the accuracy of this spreadsheet, but it seems to be helpful.

You want to see a trapezoidal shape like this. 

Mach Motor Config



Mach4 Step 5 - Input Signals Tab:

Mach's Input Signals tab should be fully populated from the values you entered in the ESS config, you should not need to do anything here.  NEVER SET A SIGNAL ACTIVE LOW HERE, ONLY SET A SIGNAL ACTIVE LOW IN THE ESS PINS CONFIG!

Mach Input Signals


Mach4 Step 6 Output Signals - Tab:

Mach's Output Signals tab should be fully populated from the values you entered in the ESS config, you should not need to do anything here.  NEVER SET A SIGNAL ACTIVE LOW HERE, ONLY SET A SIGNAL ACTIVE LOW IN THE ESS PINS CONFIG!

 Mach Output Signals


Mach4 Step 7 - MPGs Tab:

Mach's MPGs tab.  We provide 6 encoders for the 6 motors, 1 spindle encoder, and 3 auxiliary (extra) encoders.   If you want to see the encoders counting, go to Mach4's Menu -> Diagnostic -> ESS, and then look at the lower middle of that window for the 10 encoders (the spindle had counted up to 52).

Encoder 0 is mapped to Motor 0.
Encoder 1 is mapped to Motor 1.
Encoder 2 is mapped to Motor 2.
Encoder 3 is mapped to Motor 3.
Encoder 4 is mapped to Motor 4.
Encoder 5 is mapped to Motor 5.

Aux Encoder 0, 1, and 2 can be used anywhere you want to.

You use the Mach Config MPG window to assign the Encoders to the MPGs.

You need lua to assign a MPG to an axis.

MPG0 is assigned to the X Axis
MPG1 is assigned to the Y Axis
MPG2 is assigned to the Z Axis


ESS Encoder Diagnostic view

  This screen shot is just meant to show the MPGs, you will want to set yours up according to your needs. 

Mach MPGs tab


Mach4 Step 8 - Spindle Tab:

Mach's Spindle tab.  This is similar to the pulley window in Mach3.   Typically, you will only need to configure Row 0, and your settings at the bottom of the window. 

  • Set the desired spindle MinRPM in the Spindle tab of the Mach4 config. In Mach4, this may be nonzero.  A value of 0 allows a spindle S0 command to output a PWM with a zero duty cycle or no step pulses in Step/Dir mode.  A value larger than 0 (i.e. 500) would bump up all S commands to that minimum value. 
  • Set the desired spindle MaxRPM in the Spindle tab of the Mach4 config. You will typically want this to match the value you enter in Max Spindle Motor RPM in the bottom, just to avoid confusion.  For this example, I picked 24,000 RPM, but you should use whatever is the maximum RPM for your Spindle.  Your max RPM could be MUCH lower.
  • You may need to set your Accel and Decel Time to allow for your spindle to speed up or slow down.
  • Feedback Ratio is only modified if you have up or down gearing on your spindle to change your RPMs.  This will allow for your encoders to account for the gearing change in the measured spindle RPM.
  • If necessary the generated PWM signal can be inverted in the Pins Config tab of the ESS Config.
  • The Max Spindle Motor RPM should match the Max RPM in Row 0, jsut to avoid confusion.
  • The Step/Dir Spindle Axis should be left as none, unless you are following the Spindle Step/Dir mode setup guide.

Spindle speed is fully adjustable between 0% and 100% (this would be duty cycle in PWM mode), using the M3 S### command etc. within Mach4. In Step and Direction mode we would generate between 0 and 24,000 pulses per second.  In the example shown below M3 S24000 will generate a full on signal, M3 S12000 will generate a half speed signal and M3 S0 will stop it (as would the M5 command). 

We covered the initial ESS setup of the Spindle back in step #10.

Here is a video on YouTube showing how to set up Spindle PWM with a FWD and Reverse output as well.

The Spindle works with Step/Dir mode.  You will need to set it up as an OB motor, which is shown here.

Here is a short FAQ article on the Mach4 Spindle buttons.

 Mach Spindle Config


Mach4 Step 9 - Tool Path Tab:

Mach's Tool Path tab has nothing to do with the SmoothStepper setup, but it may be relevant to your application.



Mach4 Step 10 - Plugins Tab:

You may enable any plugins you need in this tab.



Mach4 Step 11 - Mach Config Completed:

Press 'OK' to save and exit the Mach Configuration. 



Mach4 Step 12 - Backing Up:

Once you have Mach4 running the way you want it to, make a copy (or many copies) of your whole "C:\Mach4\" or "C:\Mach4Hobby\" or "C:\Mach4Industrial\" folder and store it somewhere safe.  I have one copy at a relative's house on a USB stick, and another copy on   If I ever need to restore or replace my computer, I can just install Mach4, and then use my copy of the "Mach4" folder to replace the one on the PC and I am all set to run.  It can save hours and hours.  You should also back up your G-Code projects as well.



Mach4 Step 13 - Wrapping Up:

You are now ready to load a G-Code program and run it!  We suggest to practice running with an air cut first (no tools in your spindle) so you can see exactly what the machine will do, and make corrections to your program if necessary.  Also you should re-read all of the safety information you have, including ours.

Documentation (Manual) pages:



This concludes the Getting Started walk through.  If you need more help, please look at our Troubleshooting guide and our Help page.


Go to top