GRBL Settings and Calibration

Now that we have GRBL up and running, it’s time to get the settings for GRBL lined up with our machine. GRBL has a list of internal variables which must be customized for the machinery connected to the controller. These internal settings consist of things like customizing the steps/mm of the stepper motor/driver/axis type and setting up the directions and enabling optional features. We’ll start out with a list of the settings used by GRBL, note that these are settings for a Big Ox type machine with belt drive and 4 axis motors. Each is followed by a quick reference of what it does.

Factory GRBL Settings Reference

$0=10 (step pulse, usec) – This is the width of the step pulse in microseconds sent to the stepper drive
$1=255(step idle delay, msec) – This is the delay in milliseconds after a move instruction before the stepper motors are disabled. Setting this to 255 keeps motors always enabled.
$2=1 (step port invert mask: 00000000) – These are binary mask bits that set the polarity of the step pulse. 0 = normally low, high pulse, 1 = normally high, low pulse. Only the last 3 bits (LS) are used.
$3=3 (dir. port invert mask: 00000011) – Binary mask bits for the direction signal to the stepper driver. 0 = normally low, 1 = normally high. Again, only the last 3 LSB are used, ZYX. If you motor goes the wrong direction, reverse the setting of the relevant bit.
$4=1 (step enable invert, bool) – direction of the enable line. 0 = normally low, positive direction, 1 = normally high, negative direction.
$5=0 (limit pins invert, bool) – inverts the polarity of the limit switch inputs (normally high, active low)
$6=0 (probe pin invert, bool) – inverts the polarity of the Probe input (normally high, active low)
$10=3 (status report mask: 00000011) – This setting determines what Grbl real-time data it reports back to the user when a ‘?’ status report is sent.
$11=0.020 (junction deviation, mm) – This setting determines the speed algorithm when GRBL approaches a corner. Usually not altered
$12=0.002 (arc tolerance, mm) – This setting has to do with how GRBL does arcs by breaking them into many small line segments. Not usually required to be altered.
$13=0 (report inches, bool) – Changes the units reporting from mm to inches
$20=0 (soft limits, bool) – enable/disable soft limits (numerical entry)
$21=0 (hard limits, bool) – enable/disable hard limits (switches)
$22=1 (homing cycle, bool) – enable/disable homing cycle
$23=3 (homing dir. invert mask: 00000011) – sets direction of travel for homing cycle for each axis. Last 3 bits set direction for ZYX respectively
$24=200.000 (homing feed, mm/min) – speed of movement for last part of homing cycle
$25=1000.000 (homing seek, mm/min) – speed of movement for first part of homing cycle
$26=50 (homing debounce, msec) – debounce time in milliseconds for homing switches
$27=1.0 (homing pull-off, mm) – amount of pullback when homing routine hits a switch. Ensures that switches are not still activated after homing cycle if limit switches are enabled.
$100=26.730 (x, step/mm) – Steps per mm for X axis
$101=26.730 (y, step/mm) – Steps/mm for Y axis
$102=200.000 (z, step/mm) – Steps/mm for Z axis. – These 3 are the calibration values for the 3 axes, and compensate for the leadscrew pitch or belt teeth/mm, microstepping, and stepper motor resolution.
$110=3500.00 (x max rate, mm/min) – maximum speed for the X axis
$111=3500.00 (y max rate, mm/min) – Maximum speed for the Y axis
$112=2000.00 (z max rate, mm/min) – Maximum speed for the Z axis
$120=50.000 (x accel, mm/sec^2) – acceleration constant for the X axis
$121=50.000 (y accel, mm/sec^2) – acceleration constant for the Y axis
$122=50.000 (z accel, mm/sec^2) – acceleration constant for the Z axis
$130=564.000 (x max travel, mm) – Maximum axis travel for the X axis. Used for soft limits
$131=750.000 (y max travel, mm) – Maximum axis travel for the Y axis. Used for soft limits
$132=55.000 (z max travel, mm) – Maximum axis travel for the Z axis. Used for soft limits

These are minimal descriptions of what each setting does. For more information and detailed explanations of each setting, see the Settings Reference Section of the GRBL documentation at:

GRBL Wiki

Setting up Your Machine

The above settings normally have to be gone through with a fine tooth comb when setting up your machine for the first time. After that, they can usually be forgotten about since nothing on your machine should change after initial setup. The values above are stored in the Arduino in non-volatile memory, so they remain set even through power cycles. Note that setting these is different depending on what G-Code sender program you use. Refer to the documentation for the program to see how to modify these values.

Normally the first thing to set is the stepper driver parameters. Leave the stepper pulse width setting at the default unless the stepper drivers you have require a different setting. In any case, do not set this to less than 10uS. The Step Idle Delay I usually set to 255mS. This makes sure the motors are always energized after a move is finished. This locks the axes positions in place so you don’t accidentally move the axis and lose it’s position in the software. Having said this, you need to have stepper drivers that reduce the current to the motors automatically when they are not moving, or the motors will overheat very quickly. If you apply full holding current to the motor, it may destroy itself. Make sure that your drivers have this reduced current feature before setting this parameter to 255. Otherwise, set it to 254 or less to protect your motors. The next group of settings is the step port invert and direction port invert settings. Test your system out by firing up your G-Code sender program of choice and trying out the jog buttons. Direction bits need to be set first. Each axis needs to be tested to make sure it is going in the right direction. The usual defaults are:

X axis: Right is +, Left is –

Y axis: Back is +, forward is –

Z axis: Up is +, down is –

Set the bits to high on any axis that is moving in reverse. Note that the setting is in Decimal, even though the bit mask is binary. So, 00000001 would be entered as a 1, 00000111 would be entered as a 7. The pulse bits usually do not require changing, since almost all drivers require a positive going pulse to step. Check your driver documentation to see if these need to be changed. Another reason to change these would be a stepper driver module that uses a common ground on its inputs rather than a common positive. The next 3 settings just invert the polarity of the relevant signals if required. Again, check your documentation for the stepper drivers to see what they require for an enable polarity. It is usually high = disabled, low = enabled. The Limit Switch and Probe settings depend on how you wire these up as to what polarity is required.

The next pair of settings, Junction Deviation and Arc Tolerance rarely require change. See GRBL detailed documentation on what these do.

The next setting, Report Inches, is pretty self-explanatory. If you are a dinosaur that likes your settings in inches, by all means feel free to change this from the default mm. However, keep in mind that the native units for the system are in mm, so changing to inches may introduce slight conversion errors, and your values are almost never going to be even, whole numbers. Also, keep in mind that your other software like g-code senders and CAD programs will need to be set to inches as well. No mixing of units allowed.

The next 3 settings are simply enable signals. Usually you would only set soft limits if you did not have electrical limit switches on your axes. I highly recommend homing switches, they do make life easier for machine setup. The homing direction invert settings set the direction that the axes move in when you hit the homing button. They should be set so that the direction of movement is toward your homing switches wherever you decide to place them. You can home to any quadrant of the machine simply by placing the homing switches in that quadrant. There are a lot of opinions about homing and where the homing point should be, but ultimately it is your decision as to where you like home to be.

The Homing Seek and Feed Speed settings need to be set as well. I like to have the Seek speed fairly fast so it doesn’t take all day to do a homing cycle, but you need to be careful that it is not set too fast so the machine can’t stop in time when it hits a homing switch and crashes into the end stops on the axis. The Feed speed setting should be, as a rule of thumb, about ¼ of the Seek speed. This allows the system to accurately find the switch point and repeatably home to the same place each time. If your homing does not seem consistent, try lowering the speeds. Homing Debounce is, as the description says, a small time delay to allow a mechanical switches contact to stop bouncing. Almost all mechanical switches bounce, or make multiple contacts when activated. This can confuse software, so a delay is added to ignore any changes until the delay period elapses. This allows enough time for the switch contacts to reach a stable state before the software tries to read them. 50 mS is a reasonable guess for this value. If your homing seems flakey, try increasing the delay.

Homing pull off is a small movement that moves the axis away from the switch after it finds it. This is so the same switch can be used for Homing and Limit. If the homing switch did not back off until the switch opened again, as soon as the homing cycle finished, the system would get a limit switch error and lock up in Alarm Mode. It would be impossible to reset this alarm if the switch remained activated, without physically moving the axis back. Since this scenario has a high PITA value, we don’t want to do this. The pulloff should be set to the smallest distance that reliably ensures the switch is deactivated before the homing cycle finishes.

Movement Calibration

Now that we have most of the settings out of the way, it is time to calibrate the movement of each of the axes. This is done with the Steps/mm settings for each axis. This will require a bit of calculation. With a lead or ball screw type axis, you will need some information about the pitch of the screw. This is the distance travelled for each revolution of the screw. So, a TR8*8/2 pitch lead screw will travel 2mm for each revolution of the screw. You also need to know the angular resolution of your stepper motors. Most modern motors are 1.8per step, or 200 steps per revolution. In addition, if your stepper drivers are capable of microstepping, you need to know the microstep setting. So, for a C-Beam type lead screw axis actuator, we would have:

200 steps/rev

————————– = 100 steps/mm

2mm/revolution

If you add microstepping into the equation, if you have your motor set for 4 microsteps per step,

200 x 4 steps/rev

—————————– = 400 steps/mm

2mm/rev

The calculation is similar for a belt drive:

Motor steps/rev X microsteps

————————————————- = steps/mm

Pulley teeth x belt pitch

Now that you have the correct value for the axis in question, go ahead and calculate the values for all of your Axes and enter them into the settings above. This will give you a starting point for your calibration.

Now you need to check your calibration against the machine to see if it needs adjustment. Start with an axis near one end, and an accurate stainless steel ruler, a small machinists square, and a 0.5mm mechanical pencil. Use the square against the axis rail and the edge of the carriage somewhere where it gives a fixed value. Place the square against the rail, and against some part of the axis that protrudes the farthest, and carefully make a pencil mark across the rail on the edge of the square. Then move the axis using your jog controls by the length of the ruler, and make another pencil mark across the rail in the same way as the first one. Now jog the axis back to its starting position, and use the ruler to measure the distance between the two marks. It should be exactly as indicated on your screen. If it is not, it will be necessary to adjust the calculated values above until the calculated and actual values exactly agree.

As an example, suppose I move the axis 200mm according to the jog program screen, but my pencil lines are 205mm apart. This means I have to reduce the steps/mm calibration value to compensate. I would reduce it by:

Cal constant 200

——————— = —– = 0.976.

Actual value 205

Multiply this by my existing cal constant, 200 X 0.976 = 195 steps/mm

So, I would go back and enter 195 steps/mm as my new calibration constant and repeat the test above. Keep doing this until your axis movement is bang on. Note that you may have to do a reset on the Arduino to get GRBL to use the new constants each time you change them.

Lather, rinse, and repeat for each axis on your machine. You will now have everything perfectly calibrated.

The last group of settings are the maximum speeds, accelerations, and travels for each axis. Maximum speed will depend on your motor torque, mass of the gantries, and a gazillion other factors. Very difficult to calculate. Generally just set it or 3000-5000 mm/minute and live with it. If you lose steps when moving fast, reduce the value. Acceleration is an trial and error thing. GRBL will accelerate each axis up to full speed over a certain distance. If the torque of the motors is not sufficient to accelerate the mass of the gantry to this speed in this amount of time, the motors will lose steps. So, the best way to set these is also trial and error. Set the acceleration up a bit, and run the axis back and forth several times, checking how far it moves each time using the pencil line method above. If the axis loses distance at any time, the acceleration value is probably too high. Keep increasing the acceleration until the machine starts to lose position, then back it off by about 25% to get a safe value. This will need to be done separately for each axis, since they all have different masses. Or, just set it to a median value around 100-200 and forget about it. Optimizing the acceleration curves will gain you a bit of speed in your overall machining time, but it may be such a small difference as to not make it worth the effort.

Well, I’ve been plenty verbose for this blog post. Kind of dry and no sexy pictures. But. It’s an important subject and well worth understanding. Ta Ra for now.