GRBL CNC Controller Guide – Part 2: Configuration, Homing & Z-Probe

Once your UNO R3, CNC Shield V3 and DRV8825 controller is assembled, GRBL is installed and the machine can jog correctly, the next job is configuration.

This second guide focuses on making the CNC move the correct distance, in the correct direction and at reliable speeds. We will set and calibrate steps/mm, tune maximum speed and acceleration, configure limits and homing, add a Z-probe and troubleshoot the most common GRBL setup problems.

1. The GRBL Settings That Matter Most

GRBL has many settings, but you do not need to change everything at once. For a new machine, focus on the settings that directly control distance, speed, acceleration, direction and homing.

$1 — Stepper Hold

$1 controls how long GRBL keeps the stepper drivers enabled after movement stops. A value of:

$1=255

keeps the axes enabled continuously. This can help prevent an axis from being moved by hand while the controller is idle, but it also keeps the motors energised and can increase heat. Use it only when appropriate for the machine and driver cooling.

$100, $101 and $102 — Steps per Millimetre

These values tell GRBL how many step pulses are required to move each axis by exactly 1mm.

Steps/mm = (motor full steps per revolution × microsteps) ÷ millimetres travelled per motor revolution

Example 1: 8mm Lead Screw

Assume:

• 200 full-step motor
• 1/32 microstepping
• 8mm travel per motor revolution

(200 × 32) ÷ 8 = 800 steps/mm

CNC Online's 4-start 8mm lead screw has an 8mm lead, so the axis travels 8mm per screw revolution.

Example 2: GT2 Belt and 20-Tooth Pulley

A GT2 belt has a 2mm tooth pitch. A 20-tooth pulley therefore travels:

20 × 2mm = 40mm per revolution

With a 200-step motor at 1/16 microstepping:

(200 × 16) ÷ 40 = 80 steps/mm

Theoretical Resolution Is Not the Same as Machine Accuracy

If an axis is set to 800 steps/mm, one commanded microstep represents:

1mm ÷ 800 = 0.00125mm

That is the theoretical command resolution, not a promise that the machine can physically position to 0.00125mm. Mechanical backlash, flex, runout, screw lead error, microstep non-linearity and lost steps can all be much larger.

Calibrate the Real Machine

The calculated steps/mm value is your starting point. After the machine moves reliably, command a known distance and measure the actual movement.

If an axis is slightly out, use:

New steps/mm = Current steps/mm × Commanded distance ÷ Measured distance

Example: if the axis is set to 800 steps/mm, you command 100mm, but measure 99.5mm:

800 × 100 ÷ 99.5 = 804.02 steps/mm

Enter the corrected value and repeat the test over the longest practical measured distance for better calibration.

$110, $111 and $112 — Maximum Axis Speed

These settings define the maximum travel speed for X, Y and Z in mm/min.

There is no universal value. The correct maximum rate depends on:

• Motor torque at speed
• Supply voltage and driver setup
• Lead screw, belt or other transmission
• Moving mass
• Mechanical friction
• Machine rigidity

Start conservatively. Increase one axis at a time and test repeated movements. When the motor begins to stall, miss steps or sound unstable, reduce the maximum rate and leave a sensible operating margin below that point.

$120, $121 and $122 — Acceleration

Acceleration controls how quickly each axis ramps up to speed. A machine can have a perfectly reasonable maximum speed but still lose steps if acceleration is too aggressive.

Heavy gantries normally need lower acceleration than lightweight axes. Tune acceleration only after the basic motor current and steps/mm are correct.

$130, $131 and $132 — Maximum Travel

These settings describe the usable X, Y and Z travel of the machine. They become especially important if you use homing and soft limits.

Other Settings: Spindle Speed and Laser Mode

GRBL also includes $30 and $31 for maximum and minimum spindle-speed values used by supported spindle-control outputs, and $32 for laser mode. For a conventional CNC router, laser mode should normally remain disabled ($32=0). Do not copy the spindle RPM values from another machine: they must match the actual spindle and controller interface. If your spindle or VFD is controlled separately rather than through GRBL, these settings may not control its speed at all.

2. Add Limit Switches and Homing

Limit switches serve two related purposes:

• Hard limits: stop motion when an axis reaches a physical boundary.
• Homing: give GRBL a repeatable machine reference position after startup.

For electrically noisy CNC environments, screened signal cable is strongly recommended. CNC Online's 6 Core MYLAR Screened Cable is intended for low-level signals such as limit switches. Route signal wiring away from spindle/VFD and motor power cabling where possible.

The original article used a mechanical normally-closed switch arrangement:

Normally-closed (NC) wiring can help reveal broken wires as faults, but the correct $5 input-inversion setting depends on the actual circuit. Do not copy $5=1 from an older tutorial without verifying the electrical configuration: the official GRBL documentation warns that inverted limit inputs require suitable external pull-down wiring. Test each input state before enabling hard limits.

Enable Hard Limits

Once every switch has been tested manually:

$21=1

Do not enable hard limits first and then hope the wiring is correct. Test the input state before allowing the machine to travel toward an end stop.

Enable Homing

Enable GRBL homing with:

$22=1

$23 determines which axes home in the inverted direction. It is a bitmask:

Combine values where required. For example, X + Y = 3, while X + Z = 5. With three axes, the normal combined values run from 0 to 7.

Before running a homing cycle, position the machine away from the switches and be ready to stop motion. Confirm that each axis initially travels toward the correct homing switch. Other homing settings are $24 (locate feed), $25 (search speed), $26 (debounce) and $27 (pull-off distance); set these conservatively for the machine.

If you want to use soft limits, first confirm that homing works reliably and that $130–$132 represent the correct usable machine travel. Only then consider $20=1.

3. Emergency Stop: Treat Software Stop and Power Isolation Differently

The CNC Shield has controller inputs that can be used to stop or abort GRBL motion, and the original guide showed an emergency-stop style button connected to the shield.

CNC Online stocks a 22mm Emergency Stop Button.

4. Add a Z-Probe

A Z-probe allows the controller to establish the workpiece surface automatically instead of manually lowering the cutting tool until it just touches the material.

CNC Online's Z-Probe uses a touch plate and crocodile clip.

On a typical UNO-based GRBL 1.1 controller, the probe input is UNO A5 (often marked SCL on CNC Shield V3 boards), with the other probe connection to GND. The crocodile clip attaches to the cutting tool and the touch plate rests on the workpiece. The actual pin labels can vary by shield revision, so confirm your board markings before connecting either lead.

With the spindle stopped, touch the clip and plate together and confirm that GRBL/CNCjs registers the probe input before commanding any probing movement. If the state does not change correctly, stop and check the wiring and probe polarity/settings instead of attempting a live probe.

Measure the touch-plate thickness accurately with a vernier caliper and enter that value into the probing setup. The controller needs the actual plate thickness to calculate the true workpiece Z-zero.

Keep the probe feed rate slow enough that a failed probe signal does not drive the cutter hard into the plate. Before probing against the workpiece for the first time, test the circuit manually and confirm that CNCjs/GRBL detects contact correctly.

5. Common Problems and What to Check

CNCjs Cannot Connect

Check that the UNO appears as a serial/COM port, that Arduino IDE is not still holding the same port open, and that CNCjs is set to 115200 baud.

Motor Vibrates but Does Not Turn

Check the two motor coil pairs, driver orientation, motor connector and DRV8825 current limit. Incorrect coil pairing is a common cause of a motor that only buzzes.

Axis Moves in the Wrong Direction

Use GRBL's $3 direction mask to invert the required axis.

Axis Moves the Wrong Distance

Recheck the motor's full steps/revolution, microstepping jumpers and mechanical travel per revolution. Then calibrate the actual movement and correct $100, $101 or $102.

Machine Loses Position

Reduce maximum rate and acceleration, check driver current, inspect mechanical binding and make sure the motor has enough torque for the load.

Limit Switch Triggers Randomly

Electrical noise is a common cause. Use screened cable, sensible grounding and cable routing, and keep low-level limit/probe wiring away from spindle/VFD and motor power wiring.

DRV8825 Runs Very Hot

Recheck the current limit and heatsink installation. Provide airflow where necessary. Excess current does not make a correctly sized stepper system "better"; it mainly creates more heat and can damage hardware.

6. Final Setup Checklist

• UNO and CNC Shield correctly aligned
• Microstepping jumpers recorded
• DRV8825 drivers installed in the correct orientation
• Driver current limits set for the motors
• Stepper coil pairs confirmed
• Power supply polarity checked
• GRBL uploaded successfully
• CNCjs connected at 115200 baud
• Original GRBL settings saved
• Each axis jogged safely at low speed
• Axis directions confirmed
• Steps/mm calculated and calibrated
• Maximum speed and acceleration tuned conservatively
• Limit switches tested before hard limits are enabled
• Homing direction checked before full homing travel
• Z-probe input tested before probing the workpiece
• Emergency-stop strategy tested independently of normal software operation

Final Thoughts

A GRBL controller becomes reliable when the electronics, motor setup, GRBL configuration and mechanics are treated as one complete system.

Do not copy somebody else's steps/mm, maximum speed or acceleration values and assume they will suit your CNC. Calculate the correct starting values from your own motor, microstepping and drive system, then test and calibrate the real machine.

Once the basic motion is correct, features such as homing, hard limits and Z-probing make the machine easier to set up consistently and much more practical to use.

Starting from the hardware? Return to Part 1: Hardware, GRBL & CNCjs to review the complete controller build and software setup.

Need Help With Your CNC Controller?

Every CNC setup is different.

If you are unsure about your GRBL settings, controller hardware, stepper motors, drivers, power supply, limit switches or Z-probe setup, tell us about the CNC machine you are building or upgrading and the hardware you are using.

CNC Online South Africa can help you choose the controller components and supporting hardware that best suit your CNC setup.

Email: sales@cnconline.co.za
WhatsApp: 073 352 8930