GRBL firmware – setup and description

To get started, connect to Grbl using any serial port terminal program of your choice.

Set the baud rate to 115200, 8-N-1 (8-bit, no parity, 1-stop bit.)

Once connected, you should see a Grbl prompt that looks something like this:

Grbl 1.1d [‘$’ for help]

Type $ and press Enter to prompt Grbl. The $ and Enter symbols will not be displayed. Grbl should output the following:

[HLP:$$ $# $G $I $N $x=val $Nx=line $J=line $SLP $C $X $H ~ ! ? ctrl-x]

‘$’-commands are Grbl firmware system commands used to change settings, view or change the states and modes of operation of Grbl, and also start the procedure for finding the starting position. The last four non-‘$’ commands are real-time control commands that can be sent at any time, regardless of what Grbl is currently doing. They either immediately change the behavior of a running Grbl or immediately display important real-time data, such as current coordinates (aka DRO).

GRBL firmware, setup for Arduino

$$ – View Grbl settings

To view the settings, enter $$ and press Enter after connecting to Grbl. Grbl will respond with a list of current system settings, as in the example from AST3D below. All of these settings are stored in EEPROM after power off, so they will be automatically loaded the next time you turn on your Arduino board.

x or $x=val describes a single settings parameter, with val being the value of the parameter. In previous versions of Grbl, each parameter had a description in parentheses () after it, but in Grbl, since v1.1, this, unfortunately, no longer exists. This was done to free up precious flash memory for adding new features introduced in v1.1. However, most good GUIs add descriptions to the options for you, so you always know what you’re looking at.

$0=10
$1=25
$2=0
$3=0
$4=0
$5=0
$6=0
$10=1
$11=0.010
$12=0.002
$13=0
$20=0
$21=0
$22=1
$23=0
$24=25.000
$25=500.000
$26=250
$27=1.000
$30=1000.
$31=0.
$32=0
$100=250.000
$101=250.000
$102=250.000
$110=500.000
$111=500.000
$112=500.000
$120=10.000
$121=10.000
$122=10.000
$130=200.000
$131=200.000
$132=200.000

$x=val – Change Grbl settings

The $x=val command saves or changes a Grbl configuration setting, this can be done manually by sending the appropriate command to Grbl via a serial port terminal program, but most Grbl GUIs allow you to do this in a more convenient way.

To manually change, for example, the length of the step pulse in microseconds to a value of 10µs, you must enter the following, completing the command by pressing the Enter key:

$0=10

If everything went well, Grbl will answer ‘ok’, the new settings will be saved in EEPROM and will be used until the next change. You can double-check that Grbl got and saved the correct setting value by re-typing the $$ command to view the system settings.

$x=val options in Grbl and what they mean
NOTE: The only difference between Grbl v0.9 and Grbl v1.1 is that the status output of the $10 command has changed and commands have been added for the new parameters $30/$31 – maximum/minimum spindle speed and $32 – work in laser mode. Everything else is left as it was.

$0 – Step pulse duration, microseconds

Stepper motor drivers have a limitation on the minimum step pulse duration. Check the documentation for the correct value, or just try different options. It is desirable to use the shortest pulses that the driver can reliably recognize. If the pulses are too long, you may run into problems at high feedrates and high pulse frequencies due to successive pulses overlapping each other. We recommend using durations around 10 microseconds, which is the default value.

$1 – Engine shutdown delay, milliseconds

Each time your stepper motors finish moving and stop, Grbl delays for the specified amount of time before powering off the motors. OR, you can always keep the motors on (with power applied to hold the current position) by setting this parameter to the maximum possible value of 255 milliseconds. Once again, you can keep your engines always on by setting $1=255.

Shutdown Lockout Time is the delay before shutting down the motors, during which Grbl will keep the motors in a state of holding the current position. Depending on the system, you can set this parameter to zero and disable the delay. In other cases, you may want to use a value of 25-50 milliseconds to allow the axes to come to a complete stop before turning off the motors. Shutdown is intended to help for those types of motors that should not be kept on for long periods of time without any operation. Also, keep in mind that some stepper motor drivers do not remember which microstep they stopped during the shutdown process, because of this you may experience ‘skip steps’ when you turn off / on the motors. In this case, just keep the motors always on with $1=255.

$2 – Invert stepping port, mask

This parameter controls the inversion of the step pulse signal. By default, the step pulse signal starts in a normal-low state and toggles high for the period of the pulse. After the time specified by parameter $0 has elapsed, the output switches back to the low state until the next pulse. In invert mode, the stepping pulse switches from normal high to low for a pulse period and then back to high. Most users do not need to change this setting, but it may be useful if specific SD drivers require it. For example, by inverting the output of a step pulse, an artificial delay can be provided between changes (step port invert mask:00000101).

$3 – Invert direction port, mask

This parameter inverts the direction signal for each of the axes. By default, Grbl assumes that the axis is moving in a positive direction when the direction signal is low, and in a negative direction when it is high. Often the axes in some machines do not move in the same way. This parameter will invert the direction signal for those axes moving in the opposite direction.

This mask works exactly like stepping port inversion and stores the axis inversion information in a bitmask. For tuning, you just need to send a value indicating which axes to invert. Use the values from the table above. For example, if you want to invert the direction only on the Y axis, you need to send the command $3=2 to Grbl and the parameter value read should change to $3=2 (dir port invert mask:00000010)
See table above (from $2)

$4 – Invert stepper motor enable signal, logical

By default, the stepper motor enable signal is high for off and low for on. If your build requires otherwise, simply invert the signal by entering $4=1. Disabled with $4=0. (You may need to restart the controller for the changes to take effect.)

$5 – Invert limit switch inputs, logic

By default, the limit switch inputs are pulled up by the Arduino’s built-in pull-up resistor. When the input signal goes low, Grbl treats it as a switch trip. For the opposite behavior, simply invert the inputs by entering $5=1. Disabled by command $5=0. The controller may need to be restarted for the changes to take effect.

NOTE: If you are inverting the limit switch inputs, an external pull-up resistor to ground will be required to prevent overcurrent and burning the input.

$6 – Invert contact probe input, boolean

By default, the touch probe input is pulled up by the Arduino’s built-in pull-up resistor. When an input signal goes low, Grbl treats it as a sensor trigger. For the opposite behavior, simply invert the probe input by entering $6=1. Disabled by command $6=0. The controller may need to be restarted for the changes to take effect.

NOTE: If you invert the contact probe input, an external pull-up resistor to ground is required to prevent overcurrent and burning the input.

$10 – Status output, mask

This parameter determines what real time data Grbl will return when the user requests the status with the ‘?’ command. This data includes the current state, current coordinates, current feedrate, input values, current overridden values, buffer states, and the number of the G-code instruction being executed (if included at compilation).

By default, the new report output implementation in Grbl v1.1+ includes outputting information about almost everything in the standard status output. A lot of data is hidden and only shown when its value changes. This significantly increases productivity compared to the old method and allows you to get updated machine data much faster, and in a larger volume. The documentation for the interface gives a general idea of how it works, although it is mostly intended only for GUI developers or the curious.

For simplicity and convenience, Grbl v1.1 has only two options for this parameter. Both are used by users and developers mainly for debugging purposes.

Current coordinates can be configured to display either machine coordinates (MPos:) or work coordinates (WPos:), but not both. Turning on work coordinates is useful in some scenarios with direct control via a serial terminal, but machine coordinates should be used by default.
The output of information about the use of the buffer in the scheduler and serial port receiver Grbl can be enabled. This shows the number of blocks or bytes available in the corresponding buffer. This is usually needed to evaluate the performance of Grbl when testing streaming interfaces. This option should be disabled by default.
Use the table below to determine which options to enable/disable. Just add the values in the lines containing the parameters to include and store the resulting value in Grbl. For example, a report containing machine coordinates without buffer data corresponds to $10=1. Work coordinates and buffer information correspond to $10=2.

Report type Value Description
Coordinate Type 1 Enabled MPos:. Disabled WPos:.
Data Buffer 2 Enabled Buf: This field displays the amount of free space in the scheduler and receiver buffers of the serial port.

$11 – Deviation at the joints, mm

The specified amount of deflection at the joints is used by the acceleration control module to determine how fast it is possible to move through the joints of the segments of the path programmed in the G-code. For example, if a path in the G-code contains a 10 degree cusp and the machine is moving towards it at full speed, this parameter will help you determine how much you need to slow down to complete the turn without losing steps.

The calculation is done in a rather complicated way, but in general, higher values give faster cornering speeds, increasing the risk of losing steps and losing positioning. Smaller values make the control module more accurate and will result in neater and slower corner handling. So if you ever run into a problem with corners being too fast, decrease the value to make the machine slow down before going through the corners. If you want the machine to go through seams faster, increase the value of this parameter. The curious can follow the link and read about Grbl’s corner handling algorithm, which takes into account both the speed and the angle at the junction, in a simple, efficient and reliable way.

$12 – Deviation from the arc, mm

Grbl performs G2/G3 circles, arcs and helixes, breaking them up into many tiny segments so that the error of deviation from the arc does not exceed the value of this parameter. You will most likely never need to change this setting, as 0.002mm is below the resolution of most CNC machines. However, if you find that your circles are too angular, or arc traversing is too slow, adjust this setting. Smaller values give better accuracy, but may slow performance by overloading Grbl with too many small lines. Conversely, higher values result in less processing precision, but may improve speed because Grbl will have to deal with fewer lines.

For the curious, let’s clarify that the deviation from the arc is defined as the maximum length of the perpendicular drawn from the segment connecting the ends of the arc (aka the chord) to the intersection with the point of the arc. Using the basics of geometry, we calculate how long the arc needs to be divided into segments so that the error does not exceed the specified value. Modeling arcs in this way is remarkable in the sense that segments are optimally long from a performance point of view, and accuracy is never lost.

$13 – Report in inches, boolean

Grbl displays the coordinates of the current position in real time, so that the user always has an idea where the machine is currently located, as well as the parameters for offsetting the origin and measurement data (probing). By default, the output is in mm, but with the $13=1 command, you can change the parameter value and switch the output to inches. $13=0 returns output in mm.

$20 – Soft borders, boolean

Soft Boundaries is a security setting designed to help avoid moving far beyond the allowed area, which could break or destroy valuable items. It works at the expense of information about the current position and the limits of permissible movement along each of the axes. Each time Grbl sends a movement G-code, it checks to see if it will go out of bounds. And in the event that a boundary violation occurs, Grbl, wherever it is, immediately executes a feed hold command, stops the spindle and cooldown, and then raises an alarm to indicate the problem. The current position is not reset, as the stop does not occur as a result of an emergency forced stop, as is the case with hard limits.

NOTE: Soft bounds require support for the home position procedure to be enabled and the maximum bounds for movement to be carefully adjusted, since Grbl needs to know where the allowed bounds are. $20=1 to enable, and $20=0 to disable.

$21 – Hard Bounds Boolean

Hard borders generally work the same as soft borders, but use hardware switches. As a rule, you connect limit switches (mechanical, magnetic or optical) at the end of each of the axes, or at points that you think will cause problems during the movement. When the switch trips, it will immediately stop any movement, stop the cooling and the spindle (if connected), and go into emergency mode, requiring you to check the machine and reset the controller.

To use hard limits with Grbl firmware, the corresponding pins are pulled up by an internal resistor, so all you have to do is connect a normally open limit switch between the pin and ground and enable hard limits with $21=1. (Disabling – command $21=0.) We strongly recommend that you take care of the suppression of electrical interference and interference that can affect measurements. If you want to check the limits for both ends of the same axis, simply connect two switches in parallel between the pin and ground, so that tripping either of them will trigger a hard limit.

Keep in mind that hard limit triggering is treated as an exceptional event that will stop immediately and may result in lost steps. Grbl does not have any feedback from the machine about the current position, so it cannot guarantee that it has an idea of where it really is. So if a hard boundary violation occurs, Grbl will go into an endless loop of Crash mode, giving you a chance to check the machine and requiring you to reset Grbl. Please note that this feature is for security purposes only.

$22 – Search start position, boolean

Ahhh, searching for a starting position. For those new to the world of CNC: The home position search routine is used to accurately and accurately find a known machine point each time Grbl is turned on between sessions. In other words, you always know exactly where you are at any given time. Whether you were just about to start work or moved on to the next operation, and at that time the power went out, in any case, Grbl will restart and have no idea where it is now. All you have to do is figure out where you are right now. With a starting position, you always have a reference point of reference, so all that is required in this case is to start the procedure for finding the starting point and continue working from where you left off.

To set up the procedure for finding the starting position, you will need to have securely fixed limit switches at some point that cannot be bumped into or moved, otherwise the reference point may be knocked down. They are usually set at the furthest points in the +x, +y, +z direction on each of the axes. Connect the limit switches to the appropriate pins and ground in the same way as the hardware limit switches and enable the home position search. If you’re interested, you can use the limit switches AND for hardware limits, AND for finding the starting position. They work great together.

By default, Grbl’s initial position search procedure first moves the Z axis in the positive direction to free up the workspace, and then performs the simultaneous movement of the X and Y axes in the positive direction. To customize the exact behavior of the start position search procedure, there are several tuning options, described below (and compilation options too.)

It should also be noted that when the home position search procedure is enabled, Grbl blocks execution of G-code move commands until the home position search is performed. This refers to the absence of movement along the axes until the lock is disabled ($X), but more on that later. Most, if not all, CNC controllers behave similarly, this is mainly for safety, to prevent the operator from making a positioning error, which is quite simple, and getting frustrated when the job is ruined. If this annoys you or you find any weird bugs, please let us know and we’ll try to work on it and make everyone happy.

NOTE: The config.h file contains many other advanced user settings. You can disable blocking at startup, specify from which axes to start the search procedure, in what order to move along them, and much more.

$23 – Invert start point direction, mask

By default, Grbl assumes that the start point limit switches are in the positive direction, it first moves in the positive Z direction, then in the positive X-Y direction, before pinpointing the start point by slowly moving back and forth near the end point. switch. If your machine has the limit switches in the negative direction, inverting the start point direction changes the direction of the axes. It works exactly like maxi stepping port inversion or direction port inversion, all you have to do is enter a value from the table indicating which axes to invert to search in the opposite direction.

$24 – Feedrate when searching for the starting point, mm/min

The start point search procedure first searches for limit switches at high speed, and after finding them, moves to the start point at low speed to accurately determine its position. The feedrate when searching for the starting point is the same reduced speed. Set it to some value that provides a repeatable and accurate location of the starting point.

$25 – Starting point search speed, mm/min

Home point search speed is the initial speed at which the controller tries to find the home point limit switches. Adjust to any value that allows you to travel to the starting point in a short enough time without hitting the limit switches by moving too fast towards them.

$26 – Suppression of chatter when searching for the starting point, milliseconds

When the switches are triggered, some of them can emit electrical/mechanical noise for a few milliseconds, causing the signal to switch quickly between high and low values before the value is latched. To solve this problem, you need to suppress the signal bounce either by hardware, due to some kind of filtering, or by software, making a small delay for the bounce time. Grbl will make a short delay, but only when looking for a starting point during the fine-grained step. Set the delay value just long enough for your switches to provide a steady search for the starting point. For most cases, values of 5-25 milliseconds are fine.

$27 – Departure from starting point, mm

In order to coexist with the ability to track hard edges, in cases where the same limit switches are used to search for the start point, the search procedure, after completing the determination of the position of the start point, moves from the limit switches to the specified distance. In other words, it prevents unintentional triggering of hard bounds at the end of the search procedure.

$30 – Maximum spindle speed, RPM

Sets the spindle speed corresponding to the maximum voltage at the PWM output, equal to 5V. It is allowed to set higher spindle speeds in the program, but the PWM output still cannot be more than 5V. By default, Grbl builds a linear relationship of 255 samples between the maximum-minimum spindle speed and voltages at the PWM output from the 5V-0.02V range. A PWM value of 0V means the spindle is off. Note that there are additional options in the config.h file that affect this behavior.

$31 – Minimum spindle speed, RPM

Sets the spindle speed corresponding to the minimum PWM output voltage of 0.02V (0V means disabled). Smaller RPM values will be accepted by Grbl, but the PWM output voltage will not be less than 0.02V, unless it is zero. If it is 0, then the spindle is disabled and the PWM output is always 0V.

$32 – Laser mode, logic

If enabled, Grbl, in the event that the spindle speed (laser power) is changed by the S command, will continue to move from point to point in accordance with the given sequence of G1, G2, or G3 commands. The value of the duty cycle of the PWM, which is responsible for controlling the speed of the spindle, will change during the movement immediately, without stopping. Be sure to read the Grbl laser mode manual and the documentation for your laser before enabling this mode. Lasers are very dangerous. They can instantly blind you or cause a fire. Grbl Firmware, as stated in its GPL license, accepts no liability for any harm resulting from the use of this software.

If this option is disabled, then Grbl will behave as usual, interrupting the movement every time it encounters a command to change the spindle speed S. This is standard behavior for milling machines, forming a pause so that the spindle has time to change its speed.

$100, $101 and $102 – [X,Y,Z] steps/mm

Grbl needs to know how far each motor step actually moves the tool. To calibrate the pitch/mm ratio for your machine, you need to know the following:

Movement in mm corresponding to one revolution of your engine. It depends on the size of the belt drive gears or the screw pitch.
Number of full steps per motor revolution (typically 200)
The number of microsteps per step for your controller (usually 1, 2, 4, 8, or 16). Tip: Using large microstepping values (for example, 16) can reduce the torque of your motor, so use the lowest value that provides the desired axis accuracy and comfortable operating characteristics.
The step/mm value can then be calculated using the formula: steps_per_mm = (steps_per_revolution*microsteps)/mm_per_rev

Calculate these values for each of the axes and write the settings to Grbl.

$110, $111 and $112 – [X,Y,Z] Maximum speed mm/min

These parameters set the maximum speed at which you can move along each of the axes. When Grbl plans a move, it checks individually for each axis whether or not its maximum speed will be exceeded. If so, it will slow down so that the maximum speed value is not exceeded. This means that each of the axes has its own maximum speed, which is extremely useful for limiting the speed of the typically slower Z-axis.

The easiest way to find the right values is to test each axis over and over again by slightly increasing the speed and performing a move action. For example, to test the x-axis, send Grbl a command like G0 X50 with a travel distance large enough to accelerate to maximum speed. The maximum value will be reached when your stepper motor stalls. It will make a buzzing sound, but nothing bad will happen to it. Set a value 10-20% less than detected to account for wear, friction, and weight of your work head/tool. Repeat the process for the remaining axes.

NOTE: These values also determine the maximum travel speed when executing a G0 command.

$120, $121, $122 – [X,Y,Z] Acceleration, mm/sec^2

These parameters set the acceleration parameters in mm/sec per second. Simply put, a smaller value makes the Grbl smoother in motion, while a larger one results in sharper movements and reaching the desired feedrate much faster. As in the case of maximum speeds, each of the axes has its own acceleration value, which are independent of each other. This means that in the case of multi-axis movement, the acceleration will correspond to the slowest of the moving axes.

Again, as with the maximum speeds, the easiest way to determine the value of these parameters is to individually test each of the axes, slowly increasing the values until the motor stalls. Finish tuning by keeping the value 10-20% less than the value found. This will take into account wear, friction and mass inertia. We strongly recommend that you rough-test a number of G-code programs before finally settling on your chosen values. Sometimes the load on your machine may be different when moving in several axes at the same time.

$130, $131, $132 – [X,Y,Z] Maximum travel, mm

This parameter specifies the maximum travel distance in mm from one end of each axis to the other. They only make sense if you’ve enabled soft bounds (and the search for a starting point), since they’re only used by the soft bounds checker to detect out of bounds during a move.