Grbl Configuration

From ShapeOko
Jump to navigation Jump to search

The below is intended to document how one would go about configuring Grbl 0.8 for a ShapeOko using GT2 belting (the numbers would be the same for 0.9, but the storage keys are slightly different). (See Rated torque on pulleys?? Why is there not a problem here? for a discussion of GT2 vs. MXL.) The values used should be those of a stock ShapeOko 2, and the defaults for acceleration, &c. are conservative and should be re-visited and re-set to match one's machine configuration and one's needs. See Fine Tuning.

All of the below is made much easier by DrRob's nifty on-line Grbl calculator: Currently on[1]

There is a belt calculator here: (see BuildLog.Net - Belt Calculators for an imperial version).

Discussion of the settings here: Configuring Grbl v0.8.


Please note that it is necessary to reset the Arduino running Grbl so that it will re-load configuration variables.[3]

The following things affect how far the machine moves:

  • # of steps the motor has / the degrees which it moves per normal step. Values are 200 or 400, 1.8 or 0.9 degrees
  • motor micro-stepping --- this is an option which can be configured in the controller, basically it tricks the motor into moving less than a full step for each commanded step. Values range from 2x to 16x
  • the pitch of the belt --- GT2 belts as used on the SO2 have a 2mm pitch
  • the number of teeth on the pulley which determines its diameter and how far it moves the machine for a full rotation
  • how far the belt has stretched --- this is a very minor adjustment which should be applied after everything else.

For X and Y:

Calculation of steps.

  • Motor Poles 200 steps / rev[4]
  • Microsteps 8 micros/step[5]
  • Pulley teeth 20 teeth[6]
  • Belt Pitch 2mm[7]

gives us values of:

  • Resolution 40 Steps / mm
  • Resolution 25.000 µm/pulse

The resolution is: 8 microstep/step * 200 step/rev * 1/20 rev/tooth * 1/2 tooth/mm = 40 microstep/mm.

The About page has some more information on the calculations, including the numbers for the Z-axis and a link for calculating the Z-axis.

For Z:

  • Motor 200 steps/rev
  • Driver 2 microsteps/step
  • Screw 1.25 mm/rev

The resolution is: 2 microsteps/step * 200 step/rev * 1/1.25 rev/mm = 320 microstep/mm.

Showing the units and how the numbers combine is useful for those who happen to have a different setup (say, 400 step/rev motors, or 1/16 microstepping, or an Acme screw of a different lead). If you spell out the units, you don't even have to think whether you should multiply with a value or with its reciprocal: just make it so that you get microstep/mm in the end, and you're good. For instance, for single-start 12 TPI ACME screw:

  • Motor 200 steps/rev
  • Driver 2 microsteps/step
  • Screw 12 rev/inch
  • Conversion 25.4 mm/inch

and now combine them together in the only way that gives microstep/mm:

2 microstep/step * 200 step/rev * 12 rev/inch * 1/25.4 inch/mm = 188.976378 microstep/mm.

4-start 12 TPI ACME screw? No problem:

  • Motor 200 steps/rev
  • Driver 2 microsteps/step
  • Screw pitch 12 threads/inch
  • Screw lead 4 threads/rev
  • Conversion 25.4 mm/inch

2 microstep/step * 200 step/rev * 1/4 rev/thread * 12 thread/inch * 1/25.4 inch/mm = 47.244094 microstep/mm.


There is a discussion of the settings here:

Type $ at a prompt to get it to dump the settings (per ). This will result in a text display similar to:

Grbl 0.8c

'$' to dump current settings

$0 = 40.20 (steps/mm x)
$1 = 40.20 (steps/mm y)
$2 = 320.00 (steps/mm z)
$3 = 30 (microseconds step pulse)
$4 = 500.00 (mm/min default feed rate)
$5 = 500.00 (mm/min default seek rate)
$6 = 28 (step port invert mask. binary = 00011100)
$7 = 255 (step idle delay, msec)
$8 = 25.00 (acceleration in mm/sec^2)
$9 = 0.050 (junction deviation, mm)
$10 = 0.100 (arc, mm/segment)
$11 = 25 (n-arc correction, int)
$12 = 3 (n-decimals, int)
$13 = 0 (report inches, bool)
$14 = 1 (auto start, bool)
$15 = 0 (invert step enable, bool)
$16 = 0 (hard limits, bool)
$17 = 0 (homing cycle, bool)
$18 = (homing dir invert mask, int:00000000)
$19 = 25.000 (homing feed, mm/min)
$20 = 250.000 (homing seek, mm/min)
$21 = 100 (homing debounce, msec)
$22 = 1.000 (homing pull-off, mm)

Please note that different versions of Grbl may have different settings stored for a given location --- please verify a location's purpose before changing it. Note that there have been reports of pasting all settings en masse corrupting the Arduino's EEPROM. Either type the updates in manually, or paste them one line at a time.[8]

To change a given value, just type the number of the setting which you wish to change and the desired value:


(which would set the X-axis steps to the above default if that wasn't the current value already)

If things move in the wrong direction(s) you can fix this either by puzzling out the binary logic of the $6 parameter ($7 on older versions of Grbl) or re-wiring the grey wires leading to the Stepper motors from the Arduino. A stepper motor can be reversed in several ways, so it's best to be consistent in how one does it. I reversed things by swapping the red/blue pairs (think purple). If the wiring diagram is followed, everything should be correct, with no need for any modification.

Once the machine is working and cutting, one can measure its motion / performance and then calibrate the X- and Y- axes to match one's desired precision, or change the acceleration values to match one's needed performance specifications.

Note that turning off auto cycle start requires that one begin the machine manually by typing ~.[9]

Please note that one should limit the Z-axis feed and seek rates (possibly to to no more than 250mm if using M8 threaded rod) --- if your communication/control program does not have a feature to limit this, please adjust accordingly.[10]

See also Grbl Settings.


Please note that after configuration, the machine must still be calibrated.