Grbl Configuration

$$ - View Grbl settings To view the settings, type $$ and press enter after connecting to Grbl. Grbl should respond with a list of the current system settings, as shown in the example below. All of these settings are persistent and kept in EEPROM, so if you power down, these will be loaded back up the next time you power up your Arduino. The $x=val indicates a particular setting with its setting value.

Setting	Description	config.h #define
$0	Step pulse, microseconds	DEFAULT_STEP_PULSE_MICROSECONDS
$1	Step idle delay, milliseconds	DEFAULT_STEPPER_IDLE_LOCK_TIME
$2	Step port invert, mask	DEFAULT_STEPPING_INVERT_MASK
$3	Direction port invert, mask	DEFAULT_DIRECTION_INVERT_MASK
$4	Step enable invert, boolean	DEFAULT_INVERT_ST_ENABLE
$5	Limit pins invert, boolean	DEFAULT_INVERT_LIMIT_PINS
$6	Probe pin invert, boolean	DEFAULT_INVERT_PROBE_PIN
$10	Status report, mask	DEFAULT_STATUS_REPORT_MASK
$11	Junction deviation, mm	DEFAULT_JUNCTION_DEVIATION
$12	Arc tolerance, mm	DEFAULT_ARC_TOLERANCE
$13	Report inches, boolean	DEFAULT_REPORT_INCHES
$20	Soft limits, boolean	DEFAULT_SOFT_LIMIT_ENABLE
$21	Hard limits, boolean	DEFAULT_HARD_LIMIT_ENABLE
$22	Homing cycle, boolean	DEFAULT_HOMING_ENABLE
$23	Homing dir invert, mask	DEFAULT_HOMING_DIR_MASK
$24	Homing feed, mm/min	DEFAULT_HOMING_FEED_RATE
$25	Homing seek, mm/min	DEFAULT_HOMING_SEEK_RATE
$26	Homing debounce, milliseconds	DEFAULT_HOMING_DEBOUNCE_DELAY
$27	Homing pull-off, mm	DEFAULT_HOMING_PULLOFF
$30	Max spindle speed, RPM	DEFAULT_SPINDLE_RPM_MAX
$31	Min spindle speed, RPM	DEFAULT_SPINDLE_RPM_MIN
$32	Laser mode, boolean	DEFAULT_LASER_MODE
$100	Axis 1 (X) steps/unit (mm or deg)	DEFAULT_AXIS1_STEPS_PER_UNIT
$101	Axis 2 (Y) steps/unit	DEFAULT_AXIS2_STEPS_PER_UNIT
$102	Axis 3 (Z) steps/unit	DEFAULT_AXIS3_STEPS_PER_UNIT
$103	Axis 4 (A) steps/unit	DEFAULT_AXIS4_STEPS_PER_UNIT
$104	Axis 5 (B) steps/unit	DEFAULT_AXIS5_STEPS_PER_UNIT
$105	Axis 6 (C) steps/unit	DEFAULT_AXIS6_STEPS_PER_UNIT
$110	Axis 1 (X) Max rate, unit/min	DEFAULT_AXIS1_MAX_RATE
$111	Axis 2 (Y) Max rate, unit/min	DEFAULT_AXIS2_MAX_RATE
$112	Axis 3 (Z) Max rate, unit/min	DEFAULT_AXIS3_MAX_RATE
$113	Axis 4 (A) Max rate, unit/min	DEFAULT_AXIS4_MAX_RATE
$114	Axis 5 (B) Max rate, unit/min	DEFAULT_AXIS5_MAX_RATE
$115	Axis 6 (C) Max rate, unit/min	DEFAULT_AXIS6_MAX_RATE
$120	Axis 1 (X) Acceleration, unit/sec^2	DEFAULT_AXIS1_ACCELERATION
$121	Axis 2 (Y) Acceleration, unit/sec^2	DEFAULT_AXIS2_ACCELERATION
$122	Axis 3 (Z) Acceleration, unit/sec^2	DEFAULT_AXIS3_ACCELERATION
$123	Axis 4 (A) Acceleration, unit/sec^2	DEFAULT_AXIS4_ACCELERATION
$124	Axis 5 (B) Acceleration, unit/sec^2	DEFAULT_AXIS5_ACCELERATION
$125	Axis 6 (c) Acceleration, unit/sec^2	DEFAULT_AXIS6_ACCELERATION
$130	Axis 1 (X) Max travel, unit	DEFAULT_AXIS1_MAX_TRAVEL
$131	Axis 2 (Y) Max travel, unit	DEFAULT_AXIS2_MAX_TRAVEL
$132	Axis 3 (Z) Max travel, unit	DEFAULT_AXIS3_MAX_TRAVEL
$133	Axis 4 (A) Max travel, unit	DEFAULT_AXIS4_MAX_TRAVEL
$134	Axis 5 (B) Max travel, unit	DEFAULT_AXIS5_MAX_TRAVEL
$135	Axis 6 (C) Max travel, unit	DEFAULT_AXIS6_MAX_TRAVEL

$x=val - Save Grbl setting The $x=val command saves or alters a Grbl setting, which can be done manually by sending this command when connected to Grbl through a serial terminal program. You can check if Grbl has received and stored your setting correctly by typing $$ to view the system settings again.

Grbl settings:

$0 – Step pulse, microseconds Stepper drivers are rated for a certain minimum step pulse length. Check the data sheet or just try some numbers. You want the shortest pulses the stepper drivers can reliably recognize. If the pulses are too long, you might run into trouble when running the system at very high feed and pulse rates, because the step pulses can begin to overlap each other. We recommend something around 10 microseconds, which is the default value.

$1 - Step idle delay, milliseconds Every time your steppers complete a motion and come to a stop, Grbl will delay disabling the steppers by this value. OR, you can always keep your axes enabled (powered so as to hold position) by setting this value to the maximum $1=255 milliseconds. Set $1=0 will disable it. The stepper idle lock time is the time length Grbl will keep the steppers locked before disabling. You may need 25-50 milliseconds to make sure your axes come to a complete stop before disabling. This is to help account for machine motors that do not like to be left on for long periods of time without doing something. However, keep in mind that some stepper drivers don't remember which micro step they stopped on, so when you re-enable, you may witness some 'lost' steps due to this. In this case, just keep your steppers enabled via $1=255.

$2 – Step port invert, mask This setting inverts the step pulse signal. By default, a step signal starts at normal-low and goes high upon a step pulse event. After a step pulse time set by $0, the pin resets to low, until the next step pulse event. When inverted, the step pulse behavior switches from normal-high, to low during the pulse, and back to high.

Setting Value	Mask	Invert X	Invert Y	Invert Z	Invert A	Invert B
0	00000000	N	N	N	N	N
1	00000001	Y	N	N	N	N
2	00000010	N	Y	N	N	N
3	00000011	Y	Y	N	N	N
4	00000100	N	N	Y	N	N
5	00000101	Y	N	Y	N	N
6	00000110	N	Y	Y	N	N
7	00000111	Y	Y	Y	N	N
8	00001000	N	N	N	Y	N
9	00001001	Y	N	N	Y	N
10	00001010	N	Y	N	Y	N
11	00001011	Y	Y	N	Y	N
12	00001100	N	N	Y	Y	N
13	00001101	Y	N	Y	Y	N
14	00001110	N	Y	Y	Y	N
15	00001111	Y	Y	Y	Y	N
16	00010000	N	N	N	N	Y
17	00010001	Y	N	N	N	Y
18	00010010	N	Y	N	N	Y
19	00010011	Y	Y	N	N	Y
20	00010100	N	N	Y	N	Y
21	00010101	Y	N	Y	N	Y
22	00010110	N	Y	Y	N	Y
23	00010111	Y	Y	Y	N	Y
24	00011000	N	N	N	Y	Y
25	00011001	Y	N	N	Y	Y
26	00011010	N	Y	N	Y	Y
27	00011011	Y	Y	N	Y	Y
28	00011100	N	N	Y	Y	Y
29	00011101	Y	N	Y	Y	Y
30	00011110	N	Y	Y	Y	Y
31	00011111	Y	Y	Y	Y	Y

$3 – Direction port invert, mask This setting inverts the direction signal for each axis. By default, Grbl assumes that the axes move in a positive direction when the direction pin signal is low, and a negative direction when the pin is high. This setting will invert the direction pin signal for axes that move the opposite way. This invert mask setting works exactly like the step port invert mask and stores which axes to invert as bit flags. To configure this setting, you simply need to send the value for the axes you want to invert. Use the table above. For example, if want to invert the Y axis direction only, you'd send $3=2 to Grbl and the setting should now read $3=2 (dir port invert mask:00000010)

$4 - Step enable invert, boolean By default, the stepper enable pin is high to disable and low to enable. If your setup needs the opposite, just invert the stepper enable pin by typing $4=1. Disable with $4=0. (May need a power cycle to load the change.)

$5 - Limit pins invert, boolean By default $5=0, the limit pins are held normally-high with the Arduino's internal pull-up resistor. When a limit pin is low, Grbl interprets this as triggered. For the opposite behavior, just invert the limit pins by typing $5=1. NOTE: For more advanced usage, the internal pull-up resistor on the limit pins may be disabled in config.h.

$6 - Probe pin invert, boolean By default $6=0, the probe pin is held normally-high with the Arduino's internal pull-up resistor. When the probe pin is low, Grbl interprets this as triggered. For the opposite behavior, just invert the probe pin by typing $6=1.

$10 - Status report, mask This setting determines what Grbl real-time data it reports back to the user when a ? status report is sent. This data includes current run state, real-time position, real-time feed rate, pin states, current override values, buffer states, and the g-code line number currently executing (if enabled through compile-time options). By default, the new report implementation in Grbl v1.1+ will include just about everything in the standard status report. A lot of the data is hidden and will appear only if it changes. This increases efficiency dramatically over of the old report style and allows you to get faster updates and still get more data about your machine. The interface documentation outlines how it works and most of it applies only to GUI developers. To keep things simple and consistent, Grbl v1.1 has only two reporting options. These are primarily here just for users and developers to help set things up.

• Position type may be specified to show either machine position (MPos:) or work position (WPos:), but no longer both at the same time. Enabling work position is useful in certain scenarios when Grbl is being directly interacted with through a serial terminal, but machine position reporting should be used by default.
• Usage data of Grbl's planner and serial RX buffers may be enabled. This shows the number of blocks or bytes available in the respective buffers. This is generally used to helps determine how Grbl is performing when testing out a streaming interface. This should be disabled by default.

Use the table below enables and disable reporting options:

Report Type	Value	Description
Position Type	0	Enable WPos: Disable MPos:.
Position Type	1	Enable MPos:. Disable WPos:.
Buffer Data	2	Enabled Buf: field appears with planner and serial RX available buffer.

$11 - Junction deviation, mm Junction deviation is used by the acceleration manager to determine how fast it can move through line segment junctions of a G-code program path. For example, if the G-code path has a sharp 10 degree turn coming up and the machine is moving at full speed, this setting helps determine how much the machine needs to slow down to safely go through the corner without losing steps. How we calculate it is a bit complicated, but, in general, higher values gives faster motion through corners, while increasing the risk of losing steps and positioning. Lower values makes the acceleration manager more careful and will lead to careful and slower cornering. So if you run into problems where your machine tries to take a corner too fast, decrease this value to make it slow down when entering corners. If you want your machine to move faster through junctions, increase this value to speed it up. For curious people, hit this link to read about Grbl's cornering algorithm, which accounts for both velocity and junction angle with a very simple, efficient, and robust method.

$12 – Arc tolerance, mm Grbl renders G2/G3 circles, arcs, and helices by subdividing them into teeny tiny lines, such that the arc tracing accuracy is never below this value. You will probably never need to adjust this setting, since 0.002mm is well below the accuracy of most all CNC machines. But if you find that your circles are too crude or arc tracing is performing slowly, adjust this setting. Lower values give higher precision but may lead to performance issues by overloading Grbl with too many tiny lines. Alternately, higher values traces to a lower precision, but can speed up arc performance since Grbl has fewer lines to deal with. For the curious, arc tolerance is defined as the maximum perpendicular distance from a line segment with its end points lying on the arc, aka a chord. With some basic geometry, we solve for the length of the line segments to trace the arc that satisfies this setting. Modeling arcs in this way is great, because the arc line segments automatically adjust and scale with length to ensure optimum arc tracing performance, while never losing accuracy.

$13 - Report inches, boolean Grbl has a real-time positioning reporting feature to provide a user feedback on where the machine is exactly at that time, as well as, parameters for coordinate offsets and probing. By default $13=0, it is set to report in mm, if you set $13=1, it will now report in inches.

$20 - Soft limits, boolean Soft limits is a safety feature to help prevent your machine from traveling too far and beyond the limits of travel, crashing or breaking something expensive. It works by knowing the maximum travel limits for each axis and where Grbl is in machine coordinates. Whenever a new G-code motion is sent to Grbl, it checks whether or not you accidentally have exceeded your machine space. If you do, Grbl will issue an immediate feed hold wherever it is, shutdown the spindle and coolant, and then set the system alarm indicating the problem. Machine position will be retained afterwards, since it's not due to an immediate forced stop like hard limits. NOTE: Soft limits requires homing to be enabled and accurate axis maximum travel settings, because Grbl needs to know where it is. $20=1 to enable, and $20=0 to disable.

$21 - Hard limits, boolean Hard limit work basically the same as soft limits, but use physical switches instead. Basically you wire up some switches (mechanical, magnetic, or optical) near the end of travel of each axes, or where ever you feel that there might be trouble if your program moves too far to where it shouldn't. When the switch triggers, it will immediately halt all motion, shutdown the coolant and spindle (if connected), and go into alarm mode, which forces you to check your machine and reset everything. To use hard limits with Grbl, the limit pins are held high with an internal pull-up resistor, so all you have to do is wire in a normally-open switch with the pin and ground and enable hard limits with $21=1. (Disable with $21=0.) Keep in mind, that a hard limit event is considered to be critical event, where steppers immediately stop and will have likely have lost steps. Grbl doesn't have any feedback on position, so it can't guarantee it has any idea where it is. So, if a hard limit is triggered, Grbl will go into an infinite loop ALARM mode, giving you a chance to check your machine and forcing you to reset Grbl.

$22 - Homing cycle, boolean The homing cycle is used to accurately and precisely locate a known and consistent position on a machine every time you start up your Grbl between sessions. In other words, you know exactly where you are at any given time, every time. If you have homing, you always have the machine zero reference point to locate from. To set up the homing cycle for Grbl, you need to have limit switches in a fixed position that won't get bumped or moved, or else your reference point gets messed up. Usually they are setup in the farthest point in +x, +y, +z of each axes. Wire your limit switches in with the limit pins, add a recommended RC-filter to help reduce electrical noise, and enable homing. If you're curious, you can use your limit switches for both hard limits AND homing. They play nice with each other. Prior to trying the homing cycle for the first time, (1)first, ensure your machine axes are moving in the correct directions per Cartesian coordinates (right-hand rule). If not, fix it with the $3 direction invert setting. (2)Second, ensure your limit switch pins are not showing as 'triggered' in Grbl's status reports. (3)Finally, ensure your $13x max travel settings are somewhat accurate (within 20%), because Grbl uses these values to determine how far it should search for the homing switches. By default, Grbl's homing cycle moves the Z-axis positive first to clear the workspace and then moves both the X and Y-axes at the same time in the positive direction. To set up how your homing cycle behaves, there are more Grbl settings down the page describing what they do (and compile-time options as well.) Also, one more thing to note, when homing is enabled. Grbl will lock out all G-code commands until you perform a homing cycle. Meaning no axes motions, unless the lock is disabled ($X). NOTE: Check out config.h for more homing options for advanced users. You can disable the homing lockout at startup, configure which axes move first during a homing cycle and in what order, and more.

$23 - Homing dir invert, mask By default, Grbl assumes your homing limit switches are in the positive direction, first moving the z-axis positive, then the x-y axes positive before trying to precisely locate machine zero by going back and forth slowly around the switch. If your machine has a limit switch in the negative direction, the homing direction mask can invert the axes' direction. It works just like the step port invert and direction port invert masks, where all you have to do is send the value in the table to indicate what axes you want to invert and search for in the opposite direction.

$24 - Homing feed, mm/min The homing cycle first searches for the limit switches at a higher seek rate defined by Homing seek ($25), and after it finds them, it moves at a slower feed rate to home into the precise location of machine zero. Homing feed rate is that slower feed rate. Set this to whatever rate value that provides repeatable and precise machine zero locating.

$25 - Homing seek, mm/min Homing seek rate is the homing cycle search rate, or the rate at which it first tries to find the limit switches. Adjust to whatever rate gets to the limit switches in a short enough time without crashing into your limit switches if they come in too fast.

$26 - Homing debounce, milliseconds Whenever a switch triggers, some of them can have electrical/mechanical noise that actually 'bounce' the signal high and low for a few milliseconds before settling in. To solve this, you need to debounce the signal, either by hardware with some kind of signal conditioner or by software with a short delay to let the signal finish bouncing. Grbl performs a short delay, only homing when locating machine zero. Set this delay value to whatever your switch needs to get repeatable homing. In most cases, 5-25 milliseconds is fine.

$27 - Homing pull-off, mm To play nice with the hard limits feature, where homing can share the same limit switches, the homing cycle will move off all of the limit switches by this pull-off travel after it completes. In other words, it helps to prevent accidental triggering of the hard limit after a homing cycle. Make sure this value is large enough to clear the limit switch. If not, Grbl will throw an alarm error for failing to clear it.

$30 - Max spindle speed, RPM This sets the spindle speed for the maximum 5V PWM pin output. For example, if you want to set 10000rpm at 5V, program $30=10000. For 255rpm at 5V, program $30=255. If a program tries to set a higher spindle RPM greater than the $30 max spindle speed, Grbl will just output the max 5V, since it can't go any faster. By default, Grbl linearly relates the max-min RPMs to 5V-0.02V PWM pin output in 255 equally spaced increments. When the PWM pin reads 0V, this indicates spindle disabled. Note that there are additional configuration options are available in config.h to tweak how this operates.

$31 - Min spindle speed, RPM This sets the spindle speed for the minimum 0.02V PWM pin output (0V is disabled). Lower RPM values are accepted by Grbl but the PWM output will not go below 0.02V, except when RPM is zero. If zero, the spindle is disabled and PWM output is 0V.

$32 - Laser mode, boolean When enabled, Grbl will move continuously through consecutive G1, G2, or G3 motion commands when programmed with a S spindle speed (laser power). The spindle PWM pin will be updated instantaneously through each motion without stopping. Please read the GRBL laser documentation prior to using this mode.

$100, $101, $102, $103, $104 – [X,Y,Z,A,B] steps/mm, steps/degree Grbl needs to know how far each step will take the tool in reality. To calculate steps/mm for an axis of your machine you need to know:

• The mm traveled per revolution of your stepper motor, depending on the belt drive gears or lead screw pitch.
• The full steps per revolution of your steppers (typically 200 | 1.8 degrees per step)
• The microsteps per step of your controller (typically 1, 2, 4, 8, or 16). Tip: Using high microstep values (e.g., 16) can reduce your stepper motor torque, so use the lowest that gives you the desired axis resolution and comfortable running properties.

The steps/mm can then be calculated like this:

steps_per_mm = (steps_per_revolution * microsteps)/mm_per_rev

Compute this value for every axis and write these settings to Grbl.

$110, $111, $112, $113, $114 – [X,Y,Z,A,B] Max rate, mm/min; degree/min Maximum rate each axis can move. Whenever Grbl plans a move, it checks whether or not the move causes any one of these individual axes to exceed their max rate. If so, it'll slow down the motion to ensure none of the axes exceed their max rate limits. This means that each axis has its own independent speed, which is extremely useful for limiting the typically slower Z-axis. The simplest way to determine these values is to test each axis one at a time by slowly increasing max rate settings and moving it. For example, to test the X-axis, send Grbl something like G0 X50 with enough travel distance so that the axis accelerates to its max speed. You'll know you've hit the max rate threshold when your steppers stall. It'll make a bit of noise, but shouldn't hurt your motors. Enter a setting a 10-20% below this value, so you can account for wear, friction, and the mass of your workpiece/tool. Then, repeat for your other axes. NOTE: This max rate setting also sets the G0 seek rates.

$120, $121, $122, $123, $124 – [X,Y,Z,A,B] Acceleration, mm/sec^2, degree/sec^2 Axes acceleration in mm/second/second. Simplistically, a lower value makes Grbl ease slower into motion, while a higher value yields tighter moves and reaches the desired feed rates much quicker. Much like the max rate setting, each axis has its own acceleration value and are independent of each other. This means that a multi-axis motion will only accelerate as quickly as the lowest contributing axis can. Again, like the max rate setting, the simplest way to determine the values for this setting is to individually test each axis with slowly increasing values until the motor stalls. Then finalize your acceleration setting with a value 10-20% below this absolute max value. This should account for wear, friction, and mass inertia. We highly recommend that you dry test some G-code programs with your new settings before committing to them. Sometimes the loading on your machine is different when moving in all axes together.

$130, $131, $132, $133, $134 – [X,Y,Z,A,B] Max travel, mm, degree This sets the maximum travel from end to end for each axis in mm. This is only useful if you have soft limits (and homing) enabled, as this is only used by Grbl's soft limit feature to check if you have exceeded your machine limits with a motion command.