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. ***




Setting up the SmoothStepper and Mach4 Software



Getting Started: Setting up the SmoothStepper and Mach4.

Initial Mach4 setup with the current ESS plugin:
This page is for the ESS Mach4 plugin, build 184 or newer.  We are currently recommending build 202- found in line #3 of the Setup Instructions (below).  (Pictures on this page may show older plugin version numbers, but that will not affect the setup process.) 

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

  1. Backlash Compensation is now under development.
  2. THC will be the next developmental priority.
  3. Homing only backs off the switch.  A lua script is currently required to then move a known distance.
  4. Lathe/threading support needs to be implemented.

Setup instructions:

1. Run the SCU: Confirm that you have used the SCU to prepare your PC for the ESS.

2. Install Mach4: We recommend that you use Mach4 release version 3233 or newer.

  • Note for systems using MM as their jogging increment units:  If you set increment to metric, jogging works okay in Mach4   In Mach4 versions through 3365), after the first jog, it will move 25.4 times farther than expected (it switches to inches instead of staying in mm).   Release 3368 fixes this issue on their FTP site.
  • Recommended: Here is the official current release of Mach4. (We don't test against every new release, but they are usually stable.)
  • 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 every development release, so they may have hew features and fixes or they may introduce new bugs and break functionality.)  

3. Install ESS Plugin: Use the latest ESS Mach4 Plugin, build 202 - NEW

  • 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 release.  
  • The previously recommended stable release was ESS Mach4 Plugin build 193.

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

5. Start Mach4.

6. For the "Session Profile" window, if you have already created a profile, skip to step 8.  Otherwise, if you have not yet created a profile, click on "Create Profile".

Please continue with the next section, Remaining Mach4 setup for ESS.


Recent Plugin Releases:

While we are listing the older versions of the plugins, we only recommend that you use the most recent version.  In our forums, you will find documentation regarding the changes in the different versions.



Continuing with the ESS Plugin Configuration:

This section is for the newly released plugin, build 186 or newer released during summer 2016.


1. When opening Mach4, create a new profile.  This new plugin is NOT compatible with profiles made with plugins before build 184; you will need to make a new profile to work with this plugin. If you use the wx4.set, it will require lua files that may not be on your system.   With wxMach.set, we don’t have that issue, which is why we recommend this one to start with.

  • Click on 'Create Profile

Select Profile

  • Enter your new profile name, I used "NewMach4Plugin"
  • Click on the '...' and then choose wxMach.set, Press 'OK'

 Profile Information

  • Select your new profile, and press 'OK'

Select New Profile


2. 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

3. When prompted, place a check in the box next to the 'Ethernet SmoothStepper' as your motion device.  If you just installed the new version of Mach4, you MUST do this!  Press 'OK'

Select Motion Device

4. Exit Mach4, and then open Mach4 again, choosing your new profile

Select New Profile
5. Go to Menu -> Configure -> Select Motion  Device and make sure that the Ethernet SmoothStepper is selected (checked). Press ‘OK’

Menu -> Configure -> Select Motion Device...


Select Motion Device

6. Go to Menu -> Configure -> 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.

Menu -> Configure -> Mach....

Enable ESS Plugin

7. Go to Menu -> Configure -> Plugins -> and click on the “ESS – Warp9 Tech Design, Inc”Menu -> Configure -> Plugins... -> ESS

If nothing happens when you click on the ESS plugin, there are two possibilities:  The first is that the ESS plugin was not enabled in step 6 followed by a Mach4 restart.  The second is that the ESS is not powered and connected to Mach4.


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

Info Tab


9. On the “General” tab, you can:

  • Verify the IP address
  • Set the Buffer Size. :
    • 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.

  • Set the Plugin Frequency; 40 Hz is the recommended value.

imgGeneral Tab



10. On the “Motors” tab, you can:

  • Set your X, Y, Z, A, B and C axes to work in Step/Dir mode, Quadrature Mode, or CW/CCW mode. 
  • 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.
  • Set your Spindle to work in Relay, Step/Dir mode, CW/CCW mode, PWM mode or Quadrature mode.
    • 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.


    • 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.


    • In Step and Direction Mode, you control the direction of your Spindle using M3 (clockwise) or M4 (counterclockwise).  You will need to set your desired pulse width (typically 4.0 us).  There are two ways that Step/Dir may be used, depending on the type of spindle motor you are using.  One way is that your spindle motor driver will directly use the Step/Dir signals if it is commanding your spindle to a position.  The second way requires that you use a module to convert the Step/Dir signals into an analog voltage (typically 0v to 10 V DC), which is then used by your VFD to control the desired RPMs for your spindle.  To complete this portion of the spindle setup, please set it up as an OB motor, click here.


    • In CW/CCW (clockwise / counterclockwise) Mode, you control the direction of your Spindle using M3 (clockwise) or M4 (counterclockwise). The likely way that this will be used is that your spindle motor driver will directly use the CW/CCW signals to command your spindle to a position.  To complete this portion of the spindle setup, please set it up as an OB motor, click here.CW/CCW
    • In Quadrature Mode, you control the direction of your Spindle using M3 (clockwise) or M4 (counterclockwise). The likely way that this will be used is that your spindle motor driver will directly use the quadrature signals to command your spindle to a position.  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.

 Motors Tab



11. 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 optional, we strongly recommend that you assign an Alias name for each pin you wish to use.  Each Alias must be unique.  Alias names are MUCH easier to troubleshoot if you use this suggested naming convention.  This will also make it VERY obvious as to which type of signal you are dealing with at the Mach configuration level.  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 the 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 limit switches
    • no filtering on index or encoder signals

Here is an example Pins Config window.  Yours will most likely be different!

Pins Config Tab


12. 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


13. 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).

Output Signals


14. On the “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.


    Homing Tab


15. The “Support” tab provides a link back to our website.

16. Close the ESS Configuration window by pressing OK.



Completing the Mach4 Configuration:

Here is the current Mach4 Installation Manual (MIM), which details what all of the fields and settings are.    Therefore, I will skip fields that don't apply to getting most users up and running, and only explain the fields that are most relevant to getting Mach4 and your system running with an ESS.

17. Go to Menu -> Configure -> 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....


18. 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, so I will not address them here.  Please read the Mach4 Installation Manual (linked above) for more information on these settings.

  Mach General Config


19. 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)


How do you calculate your steps per unit?  Try this Excel spreadsheet made by RICH.

You want to see a trapezoidal shape like this. 

Mach Motor Config


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

 Mach Axis Mapping


21. 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 up to step #14
  • 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.
  • 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)

In this example, I have it set up to home axes in the following order, Z(1), Y(2), X(3), A(4 and slaved to X) and finally C(6).  The B axis will not be homed via switches, but will rather be homed in place.   The Z axis has soft limits enabled for locations Z=0.0 and Z = 8.0 

Mach Homing and Soft Limits


22. Mach's Input Signals tab should be fully populated from the values you entered in the ESS config.  NEVER SET IT ACTIVE LOW HERE, ONLY DO THAT IN THE ESS PINS CONFIG!

Mach Input Signals


23. Mach's Output Signals tab should be fully populated from the values you entered in the ESS config.  NEVER SET IT ACTIVE LOW HERE, ONLY DO THAT IN THE ESS PINS CONFIG!

 Mach Output Signals


24. Mach's MPGs tab.  We provide 6 encoders for 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).


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


25. 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.  With the SmoothStepper you will almost always want this to be 0.  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.
  • 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.  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.
  • The Step/Dir Spindle Axis is set automatically to the Port and Pin(s) you configured in the ESS Plugin's Output Signals tab.

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 temporarily 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


26. Mach's Tool Path tab has nothing to do with the SmoothStepper.

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

28. 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.

29.  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.



Notes on MPGs and Encoders:

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



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