You are on page 1of 58

About Grbl

Grbl is a free, open source, high performance software for controlling the motion of machines that move,
that make things, or that make things move, and will run on a straight Arduino. If the maker movement was
an industry, Grbl would be the industry standard.
Most open source 3D printers have Grbl in their hearts. It has been adapted for use in hundreds of projects
including laser cutters, automatic hand writers, hole drillers, graffiti painters and oddball drawing machines.
Due to its performance, simplicity and frugal hardware requirements Grbl has grown into a little open source
phenomenon.
In 2009, Simen Svale Skogsrud (http://bengler.no/grbl) graced the open-source community by writing and
releasing the early versions of Grbl to everyone (inspired by the Arduino GCode Interpreter by Mike Ellery).
Since 2011, Grbl is pushing ahead as a community-driven open-source project under the pragmatic
leadership of Sungeun K. Jeon Ph.D. (@chamnit).

Official Supporters of the Grbl CNC Project

Grbl is an open-source project and fueled by the free-time of our intrepid administrators and altruistic
users. If you'd like to donate, all proceeds will be used to help keep this project sustainable and to fund
supporting equipment. Thank you!

Who should use Grbl


Makers who do milling and need a nice, simple controller for their system that will run the ubiquitous
Arduino Uno. People who loathe to clutter their space with legacy PC-towers just for the parallel-port.
Tinkerers who need a controller written in tidy, modular C as a basis for their project.

Nice features
Grbl is ready for light duty production. We use it for all our milling, running it from our laptops using great
user-written GUIs or with a simple console script (included) to stream the G-code. It is written in optimized
C utilizing all the clever features of the Arduino's Atmega328p chips to achieve precise timing and
asynchronous operation. It is able to maintain more than 30kHz step rate and delivers a clean, jitter free
stream of control pulses.
Grbl is for three axis machines. No rotation axes (yet) just X, Y, and Z.
The G-code interpreter implements a subset of the NIST rs274/ngc standard and is tested with the output of
a number of CAM-tools with no issues. Linear, circular and helical motion are all fully supported.

Supported G-Codes in v0.9i

o G38.3, G38.4, G38.5: Probing


o G40: Cutter Radius Compensation Modes
o G61: Path Control Modes
o G91.1: Arc IJK Distance Modes

Supported G-Codes in v0.9h


o G38.2: Probing
o G43.1, G49: Dynamic Tool Length Offsets

Supported G-Codes in v0.8 (and v0.9)


o G0, G1: Linear Motions
o G2, G3: Arc and Helical Motions
o G4: Dwell
o G10 L2, G10 L20: Set Work Coordinate Offsets
o G17, G18, G19: Plane Selection
o G20, G21: Units
o G28, G30: Go to Pre-Defined Position
o G28.1, G30.1: Set Pre-Defined Position
o G53: Move in Absolute Coordinates
o G54, G55, G56, G57, G58, G59: Work Coordinate Systems
o G80: Motion Mode Cancel
o G90, G91: Distance Modes
o G92: Coordinate Offset
o G92.1: Clear Coordinate System Offsets
o G93, G94: Feedrate Modes
o M0, M2, M30: Program Pause and End
o M3, M4, M5: Spindle Control
o M8, M9: Coolant Control

Most configuration options can be set at runtime and are saved in eeprom between sessions and even
retained between different versions of Grbl as you upgrade the firmware. For descriptions of these G-codes,
we follow the NIST G-code guidelines and LinuxCNC.org also provides great documentation for these as
well. (G-codes) (M-codes) (Other codes) and the Shapeoko wiki attempts to list all codes supported by Grbl
with appropriate commentary.

Acceleration management
In the early days, Arduino-based CNC controllers did not have acceleration planning and couldn't run at full
speed without some kind of easing. Grbls constant acceleration-management with look ahead planner
solved this issue and has been replicated everywhere in the micro controller CNC world, from Marlin to
TinyG. Grbl intentionally uses a simpler constant acceleration model, which is more than adequate for home
CNC use. Because of this, we were able to invest our time optimizing our planning algorithms and making
sure motions are solid and reliable. When the installation of all the feature sets we think are critical are
complete and no longer requires us to modify our planner to accommodate them, we intend to research and
implement more-advanced motion control algorithms, which are usually reserved for machines only with
very high feed rates (i.e. pick-and-place) or in production environments. Lastly, here's a link describing the
basis of our high speed cornering algorithm so motions ease into the fastest feed rates and brake before sharp
corners for fast yet jerk free operation.

Limitations by design
We have limited G-code-support by design. This keeps the Grbl source code simple, lightweight, and
flexible, as we continue to develop, improve, and maintain stability with each new feature. Grbl supports all
the common operations encountered in output from CAM-tools, but leave some human G-coders frustrated.
No variables, no tool databases, no functions, no canned cycles, no arithmetic and no control structures. Just
the basic machine operations and capabilities. Anything more complex, we think interfaces can handle those
quite easily and translate them for Grbl.

New features in v0.9!


Has it really be a year and a half since the last version? Oh my how time flies.. Anyhow, this is a HUGE
update! Stability and performance was honed in and sharpened to make Grbl production quality. Here's a
summary of the new changes:

IMPORTANT:
o Default serial baudrate is now 115200! (Up from 9600)
o Z-Axis limit input on D11 has swapped with spindle enable D12 to support variable
spindle PWM output.
o No QUEUE state: Queue was removed due to it being redundant. Holds now suspend
Grbl and only allow realtime commands. Cycle start resumes, and reset exits.

NEW Super Smooth Stepper Algorithm: Complete overhaul of the handling of the stepper driver
to simplify and reduce task time per ISR tick. Much smoother operation with the new Adaptive
Multi-Axis Step Smoothing (AMASS) algorithm which does what its name implies (see stepper.c
source for details). Users should immediately see significant improvements in how their machines
move and overall performance!

Stability and Robustness Updates: Grbl's overall stability has been focused on for this version. The
planner and step-execution interface has been completely re-written for robustness and
incorruptibility by the introduction of an intermediate step segment buffer that "checks-out" steps

from the planner buffer in real-time. This means we can now fearlessly drive Grbl to it's highest
limits. Combined with the new stepper algorithm and planner optimizations, this translated to 5x to
10x overall performance increases in our testing! Also, stability and robustness tests have been
reported to easily take 1.4 million (yes, million) line G-code programs like a champ!

(x4)+ Faster Planner: Planning computations improved four-fold or more by optimizing end-to-end
operations, which included streamlining the computations and introducing a planner pointer to locate
un-improvable portions of the buffer and not waste cycles recomputing them.

Variable Spindle Speed Output: Enables a hardware PWM output for 'S' G-code commands.
NOTE: This feature requires a pin swap with the Z-limit D11 pin and spindle enable D12 pin to
access the hardware PWM on pin D12. The Z-limit pin, now on D12, should work just as it did
before.

Compile-able via Arduino IDE!: Grbl's source code may now be downloaded and altered, and then
be compiled and flashed directly through the Arduino IDE, which should work on all platforms. See
the Wiki for details on how to do it.

G-Code Parser Overhaul: Completely re-written from the ground-up for 100%-compliance* to the
G-code standard. (* Parts of the NIST standard are a bit out-dated and arbitrary, so we altered some
minor things to make more sense. Differences are outlined in the source code.) We also took steps to
allow us to break up the G-code parser into distinct separate tasks, which is key for some future
development ideas and improvements.

Independent Acceleration and Velocity Settings: Each axis may be defined with unique
acceleration and velocity parameters and Grbl will automagically calculate the maximum
acceleration and velocity through a path depending on the direction traveled.

Soft Limits: Checks if any motion command exceeds workspace limits before executing it, and
alarms out, if detected.

Probing: The G38.2, G38.3, G38.4, & G38.5 straight probe G-code commands are now supported
and connected through the A5 pin.

Tool Length Offsets: Probing doesn't make sense without tool length offsets (TLO), so we added it!
The G43.1 dynamic TLO (described by linuxcnc.org) and G49 TLO cancel commands are now
supported. G43.1 dynamic TLO works like the normal G43 TLO (NOT SUPPORTED) but requires
an additional axis word with the offset value attached. We did this so Grbl does not have to track and
maintain a tool offset database in its memory. Perhaps in the future, we will support a tool database,
but not for this version.

Improved Arc Performance: The larger the arc radius, the faster Grbl will trace it! We are now
defining arcs in terms of arc chordal tolerance, rather than a fixed segment length. This automatically
scales the arc segment length such that maximum radial error of the segment from the true arc is
never more than the chordal tolerance value of a super-accurate default of 0.002 mm.

New Grbl SIMULATOR! (by @jgeisler and @ashelly): A completely independent wrapper of the
Grbl main source code that may be compiled as an executable on a computer. No Arduino required.
Simply simulates the responses of Grbl as if it was on an Arduino.

CPU Pin Mapping: In an effort for Grbl to be compatible with other AVR architectures, such as the
1280 or 2560, a new cpu_map.h pin configuration file has been created to allow Grbl to be compiled
for them. This is currently user supported, so your mileage may vary. If you run across a bug, please
let us know or better, send us a fix! Thanks in advance!

Configurable Real-time Status Reporting: Users can now customize the type of real-time data
Grbl reports back when they issue a '?' status report. This includes data such as: machine position,
work position, planner buffer usage, serial RX buffer usage.

Updated Homing Routine: Sets workspace volume in all negative space regardless of limit switch
position. Common on pro CNCs. But, the behavior may be changed by a compile-time option
though. Now tied directly into the main planner and stepper modules to reduce flash space and allow
maximum speeds during seeking.

CoreXY Support: Grbl now supports CoreXY kinematics on an introductory-level. Most functions
have been verified to work, but there may be bugs here or there. Please report any problems you
find!

Safety Door Support: Safety door switches are now supported. Grbl will force a feed hold,
shutdown the spindle and coolant, and wait until the door switch has closed and the user has issued a
resume. Upon resuming, the spindle and coolant will re-energize after a configurable delay and
continue. Useful for OEMs that require this feature.

Full Limit and Control Pin Configurability: Limits and control pins operation can now be
interpreted by Grbl however you'd like, with the internal pull-up resistors enabled or disabled, or
reading a high or low as a trigger. This should cover all wiring and NO or NC switch scenarios.

Optional Limit Pin Sharing: Limit switches can be combined to share the same pins to free up
precious I/O pins for other purposes. When combined, users must adjust the homing cycle mask in
config.h to not home the axes on a shared pin at the same time. Don't worry; hard limits and the
homing cycle still work just like they did before.

Additional Compile-Time Feature Options: Limit/control pin state reporting, line number
tracking, real-time feed rate reporting, and more.

New features in v0.8!


A lot has happened since the v0.7. We're pushing real hard to create a simple, yet powerful CNC controller
for the venerable Arduino. Here's a list of the new things that have come to v0.8.

Multi-Tasking Run-time Commands: Feed hold with controlled deceleration for no loss of
location, Resume after feed hold, Reset, and Status Reporting.

Advanced Homing Cycle: Lots of configuration options for different types of machines from which
axes to move when to their search directions. Limit switches may also be used as hard limits as well.

Persistent Coordinate System Data: Work Coordinate Systems (G54-G59) and Pre-Defined
Positions (G28,G30) are held in EEPROM, so they'll always be set as you last set them.

Check G-Code Mode: Sets up Grbl to run through your program without moving anything, so you
can check whether or not you have any errors that Grbl may not like.

Improved Feedback: Reports real-time position, what Grbl is doing, the G-code parser state, and
stored coordinate offset values.

Startup blocks: Auto-magically runs user G-code blocks at startup or reset. Can be used to set your
defaults.

Pin-outs: Cycle start, feed hold, and abort are now pinned-out to the A0, A1, and A2 pins. Just
connect a normally-open switch to the pin and ground. That's it!

More Robust G-Code Parser with Error Checking Feedback.

And much more!

Slated for v1.0 Future Development


Grbl is constantly under development with new features being added all the time. Here's a short list of
upcoming features set for the next version, but click this link to read up the details.

Overrides: Real-time adjustment of the feedrates, spindle speed, and coolant during a cycle. We've
solved it and just need to figure out some small details before installing it.

Jogging: Set up an easy interface for users to proper jogging.

Backlash Compensation: Not sure it'll make it into the Uno version, but definitely when we support
a bigger controller.

Licensing for Grbl v0.9:


Note from the Grbl v0.9 author:

After releasing Grbl v0.8 (and prior) under the permissive MIT-license, several commercial entities have
inquired about obtaining an MIT-license for the latest version, Grbl v0.9, to use in their proprietary
products. At the time, Grbl v0.9 was developed under the "copy-left" GPLv3 license. While the strong
interest was extremely humbling, it brought up some concerns about taking steps to protect Grbl for the
open-source community but to still allow use for entrepreneurs. While the path forward is being worked out,
Grbl v0.9 will remain under the GPLv3 license, and all older versions will remain open and permissive
under the MIT-license.

Grbl(tm) v0.9 is free software distributed under the terms of the GPLv3 license reproduced below (See
COPYING for more details.) Grbl v0.9 is certified open-source software, is not in the public domain, and its
authors retain its copyright.
Grbl v0.9 is built upon the previous work in Grbl v0.8, which was released under the MIT-license.
Grbl(tm) v0.9
Copyright (c) 2012-2014 Sungeun K. Jeon
Grbl v0.9 is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Grbl v0.9 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with Grbl v0.9. If not, see <http://www.gnu.org/licenses/>.

Licensing for Grbl v0.8 (and prior):


Grbl(tm) v0.8 is free software distributed under the terms of the MIT License reproduced below. GRBL v0.8
may be used for any purpose, including commercial purposes, at absolutely no cost. No paperwork, no
royalties, no GNU-like "copyleft" restrictions, either. Just download it and use it.
Grbl v0.8 is certified open-source software. Its license is simple, liberal, and compatible with GPL. Grbl
v0.8 is not in the public domain and its authors retain its copyright.
The spirit of the Grbl v0.8 license is that you are free to use GRBL for any purpose at no cost without having
to ask us. The only requirement is that if you use GRBL v0.8, then you should give us credit by including
the copyright notice somewhere in your product documentation. A nice, but optional, way to give us further
credit is to include a statement like "This product contains source code from the Grbl CNC project" and link
to our site in a web page for your product.
Grbl v0.8 has been entirely designed, implemented, and maintained by the authors of Grbl v0.8 and its
altruistic contributors.
The MIT License (MIT)
GRBL(tm) v0.8
Copyright (c)
Copyright (c)
Copyright (c)

- Embedded CNC g-code interpreter and motion-controller


2009-2011 Simen Svale Skogsrud
2011-2013 Sungeun K. Jeon
2011 Jens Geisler

Permission is hereby granted, free of charge, to any person obtaining a copy


of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

COMPILING GRBL
Via the Arduino IDE (All Platforms):
Last updated: 2015-06-15 by chamnit. (Tested on OS X 10.10 with Arduino IDE v1.65)
Thanks to the great people working on the Arduino IDE, it has everything you need to compile grbl included
in their software package. NOTE: This method compiles the source code into a new hex and automatically
uploads it to an Arduino. You can't directly flash a pre-compiled .hex file through the IDE interface. See our
Flashing Grbl to an Arduino wiki page for how to do this if you only have a .hex file.
NOTE: Before starting, make sure that any older installation of Grbl has been completely removed from the
Arduino IDE.

NOTE: There have been reports of upload failures on some older Arduino boards. Typically, re-flashing the
Arduino boot loader fixes this problem. This can be performed by a separate Arduino quite easily, and there
are numerous online resources to show you how.
1. Download the Grbl source code (v0.9i).
o

Click the Download ZIP button on the lower right side of the home page.

Once downloaded, unzip it and you'll have a folder called grbl-master or


something similar.

2. Make sure you are using the most recent version of the Arduino IDE (last tested on
v1.61).
3. Load Grbl into the Arduino IDE as a Library.
o

Launch the Arduino IDE.

Click the Sketch drop-down menu, navigate to Include Library, and click Add
.ZIP Library, note that this still works with a folder (prior to IDE version 1.6.2
this will be Import Library..., and click Add Library...).

Select the Grbl folder inside the grbl-master folder when asked to select a
library folder you'd like to add. The correct folder only contains the source files
and an example directory.

It may take a few seconds for the Arduino IDE to import it.

NOTE: For pre-v1.05 Arduino IDE users, you will need to manually add Grbl into
your Arduino libraries, so that it will appear in the Import Library... menu.
Search the internet for how to install, then skip to step 4.

4. Open the GrblUpload Arduino example.


o

Click the File down-down menu, navigate to Examples->Grbl, and select


GrblUpload.

5. Compile and upload Grbl to your Arduino.


o

Connect your Arduino Uno to your computer.

Make sure your board is set to the Arduino Uno in the Tool->Board menu and the
serial port is selected correctly in Tool->Serial Port.

Click the Upload, and Grbl should compile and flash to your Arduino! (Flashing
with a programmer also works by using the Upload Using Programmer menu
command.)

Once you have your Grbl library set up in the Arduino IDE, you can update, replace, or modify the Grbl
source code in the library folder. On a Mac, it's located in ~/Documents/Arduino/libraries/. On
Windows, it's in My Documents\Arduino\libraries. You may need to restart the Arduino IDE for this
change to take effect.
No fuss! No muss!

For Mac OS X:
Last updated: 2012-01-29 by chamnit. (Tested on OS X 10.7, 10.6, 10.4 and the Arduino IDE r22,v1.0)
This method of compiling Grbl uses the Mac OSX terminal and command line to access the Arduino IDE's
compilers without having to use the Arduino IDE. This produces the same firmware as the Arduino IDE
method above.
First, you'll need to make sure you have the most up-to-date Arduino IDE version installed on your Mac.
The trickiest part is setting up the environment path for the compilers included in the Arduino software. To
do this, you'll need to first locate where they are. Depending on where you place your Arduino.app software,
this will usually be located in /Applications/Arduino.app for most people. The complete path is then:
/Applications/Arduino.app/Contents/Java/hardware/tools/avr/bin/

To add the compiler path: Open the Terminal.app in /Applications/Utilities.


Then type: nano ~/.bashrc to edit your shell config file.
Now add this line at the end of the file: export
PATH=$PATH:/Applications/Arduino.app/Contents/Java/hardware/tools/avr/bin/

or whatever

your path happens to be.


Press Crtl-X to exit and select Yes to save the file. Now you have added the compiler path. You will need to
close the current working window and re-open a new one for the path to be loaded correctly.
NOTE: If you are having problems, you may need to add this same PATH to your .bash_profile file. The
process is exactly the same, just switch out the names.
To compile: Once your paths are setup, all you will need to do is go to your grbl directory and type make.
(To clear all of the old compilation files from a previous build, type make clean first.) This should call avrgcc, begin compiling grbl, and create a brand new firmware file called grbl.hex that may then be flashed to
your Arduino.

For Windows:
Last updated: 2012-01-28 by txjammer. (Tested on Windows XP and the Arduino IDE r23)
You can use the Arduino platform as well since it comes with "win-avr" avrgcc.
You must add the paths the the executable's like make.exe and avrdude.exe to windows environment
variables. Right click my computer on the start menu and click Properties. Go to the Advanced tab and on
the bottom there will be a button that says environment variables. Under system variables there will be a
Variable with the name "Path". Click edit and add the paths to the executable's eg, C:\arduino00xx\hardware\tools\avr\bin;C:\arduino-00xx\hardware\tools\avr\avr\bin;C:\arduino00xx\hardware\tools\avr\utils\bin Do not erase your previous paths just add the new ones. Once this is done
you can compile the source.
For windows 7 and arduino 1.5.7

Add the following paths to your PATH variable - be sure to include ; after each one, except the last in your
PATH variable entry.
C:\Program Files (x86)\Arduino\hardware\tools\avr\avr\bin\

C:\Program Files (x86)\Arduino\hardware\tools\avr\bin\


C:\Program Files
(x86)\Arduino\hardware\arduino\sam\system\CMSIS\Examples\cmsis_example\gcc_atmel
C:\Program Files (x86)\Arduino

You will very likely need to restart your computer in order for Windows to recognize the newly added paths.

Once your path has been updated, you can open a command prompt. To do so:
Click start, in the run box, type cmd or find the command prompt in your start menu, usually in Start ->
Programs -> Accessories.
Change your working directory to the directory that contains the grbl source code:
cd C:\grblpath

type
make clean

This will output something similar to this:


rm -f grbl.hex main.elf main.o motion_control.o gcode.o spindle_control t_control.o
serial.o protocol.o stepper.o eeprom.o settings.o planner.o ts.o limits.o print.o
probe.o report.o system.o main.d motion_control.d spindle_control.d coolant_control.d
serial.d protocol.d stepper.d eepro ngs.d planner.d nuts_bolts.d limits.d print.d
probe.d report.d system.d

Type make grbl.hex or simply make


If all goes well grbl.hex should be created and you can upload to your atmega328p using avrdude. For
instructions on how to flash your newly compiled grbl.hex file to your Arduino, see this wiki entry
Ruby is optional, but if you don't edit the Makefile you will need to download ruby and in the
installation settings add the path to environment variables again. Then you can compile the full source with
flash calculation. If you don't want to install ruby, edit the Makefile (removing?) everything after ruby (on
line 84 only).
An alternative is to use Atmel Studio, a customized version of Visual Studio.
Last update: 2014-07-18 by gerritv (tested on Windows 8.1, 64bit)

Install Atmel Studio

Install the Create From Makefile Extension (Tools/Extension Manager)

run Tools/Create Project From Makefile

select the Makefile from your grbl code directory

Select Device, use ATmega328p for the Arduino Uno

In Projects/Properties, uncheck Use External Makefile

Add -DF_CPU=16000000 -mmcu=atmega328p to Project/Properties/Toolchain/AVR Gnu


Compiler/Miscellaneous Other Flags

The last 2 steps need to be done for both Debug and Release configurations
Enjoy the benefits of Visual Studio for Atmel/AVR

For Linux:
Last updated: 2012-03-02 by speters. (Tested on ???)
Make sure you have the prerequisite libraries installed: avr-gcc and arduino (sudo aptitude install arduino)
At a terminal prompt, change directories to where the grbl source code located. Then type the following to
compile and build the firmware:
make clean
make grbl.hex

For Ubuntu:
Last updated: 2014-01-20 by EliteEng.
The following has been tested on Ubuntu 11.10 and an Arduino Uno. It will compile grbl from source code
and flash it to your Arduino. It should in theory work with other flavours of debian too.
On a brand new ubuntu box, the install process goes like this:
1) install the avr build tools by running:
sudo apt-get install arduino-core make unzip

2) Compile the GRBL source code and create the firmware file:
cd /home ## or a location you want to download the source code to.
wget https://github.com/grbl/grbl/archive/master.zip
unzip master.zip
cd grbl-master
sudo make grbl.hex

3) To flash the firmware to your Arduino Uno, plug the Arduino in using the USB cable (Confirm that the
device is located at /dev/ttyACM0 and run the following command:
sudo PROGRAMMER="-c arduino -P /dev/ttyACM0" make flash

That's it, the firmware should now be installed on your Arduino.

Flashing Grbl to an Arduino


Via the Arduino IDE (All Platforms):
Last updated: 2014-07-26 by chamnit. (Tested on OS X 10.9 and Windows 7 with Arduino IDE v1.05)
Go to the Compiling Grbl wiki page for instructions on how compile and upload Grbl onto your Arduino
simply through the Arduino IDE interface. No fuss! It just requires users to download the source code and
add Grbl as a library to the IDE.

But, if all you have is a pre-compiled .hex file, you will need to use one of the methods below to flash it, as
the Arduino IDE can't flash a .hex file through the IDE interface.

For Mac OS X:
Try this first! Paul Kaplan from Inventables made this process much easier than before with a simple
GUI app called HexUploader. Let us know how it works!
Last updated: 2012-02-12 by gregrebholz. (Tested on OS X 10.7, 10.6, and 10.4 and the Arduino Uno and
IDE v1.0/r22; and OS X 10.6 and the Arduino Duemilanove and IDE v1.0)
As with compiling grbl, the tools for flashing grbl to an Arduino are included in the Arduino IDE software.
All you need to do is directly access them through the Terminal.app. The following instructions have been
tested and work for the Arduino Uno. For others, your mileage may vary.
For most people, the path to the Arduino compiler tools will be:
/Applications/Arduino.app/Contents/Resources/Java/hardware/tools/avr (Note the absence of /bin from the
compiling grbl page.) Depending on where you place the Arduino IDE, the /Applications/Arduino.app path
may be different. So, lets call your compiler tools path $AVRPATH to help shorten the following
commands.
Next you will need to find the device path to your Arduino. First, connect your Arduino to a Mac USB port.
To find the device path, from a Terminal.app window, type: /dev/tty.usb and hit Tab once or twice. This will
either give you one device path, which is your Arduino, or multiple paths, if you have more than one
usbmodem type device connected to your computer. If you have multiple, simply unplug your Arduino,
repeat the process, and eliminate the remaining devices that are still listed. Your Arduino device path should
be something like this: /dev/tty.usbmodem1811 and lets call this $DEVPATH.
To Flash Grbl: Using the Terminal.app, first make sure you're in the same directory as the grbl.hex file you
want to flash to the Arduino, which we'll call $GRBLHEX. Then, type the following commands to flash.
For Release 0023 and prior on the Uno: $AVRPATH/bin/avrdude -C$AVRPATH/etc/avrdude.conf
-pm328p -cstk500v1 -P$DEVPATH -D -Uflash:w:$GRBLHEX

For Release 0023 and prior on the Duemilanove: $AVRPATH/bin/avrdude


-C$AVRPATH/etc/avrdude.conf -pm328p -cstk500v1 -P$DEVPATH -b57600 -D -Uflash:w:$GRBLHEX

For v1.0 on the Uno: $AVRPATH/bin/avrdude -C$AVRPATH/etc/avrdude.conf -pm328p -carduino


-P$DEVPATH -D -Uflash:w:$GRBLHEX

For v1.0 on the Duemilanove: $AVRPATH/bin/avrdude -C$AVRPATH/etc/avrdude.conf -pm328p


-carduino -P$DEVPATH -b57600 -D -Uflash:w:$GRBLHEX

Note the only change between the two versions is the -c flag from the stk500v1 programmer to the arduino
programmer. This programmer flag was updated in the v1.0 IDE. If all goes according to plan, you should
see three sequential progress bars of reading, writing, and verifying and you're good to go!
Additional Mac Resources:

DANK (Last updated 2/2011)

For Windows:
Last updated: 2013-01-24 by dmalicky. (Tested on Windows XP/7 and Arduino Uno)

Flashing a hex file to your Arduino is simple with windows. First, plug in your Arduino into any USB port
of your Windows machine and then determine the assigned COM port of your Arduino.
To Determine your Arduino's COM port:

Windows XP: Right click on "My Computer", select "Properties", select "Device Manager".

Windows 7: Click "Start" -> Right click "Computer" -> Select "Manage" -> Select "Device
Manager" from left pane

In the tree, expand "Ports (COM & LPT)"

Your Arduino will be the USB Serial Port (COMX), where the X represents the COM number, for
example COM6.

If there are multiple USB serial ports, right click each one and check the manufacturer, the Arduino
will be "FTDI".

To flash a grbl hex to an Arduino:


1. Download and extract XLoader.
2. Open XLoader and select your Arduino's COM port from the drop down menu on the lower left.
3. Select the appropriate device from the dropdown list titled "Device".
4. Check that Xloader set the correct baud rate for the device: 57600 for Duemilanove/Nano (ATmega
328) or 115200 for Uno (ATmega 328).
5. Now use the browse button on the top right of the form to browse to your grbl hex file.
6. Once your grbl hex file is selected, click "Upload"
After clicking upload, you'll see the RX/TX lights going wild on your Arduino. The upload process
generally takes about 10 seconds to finish. Once completed, a message will appear in the bottom left corner
of XLoader telling you how many bytes were uploaded. If there was an error, it would show instead of the
total bytes uploaded. Steps should be similar and may be done through the command prompt.
Additional Windows HexUploader

APEHexLoader available from apecoder.co.za, is capable of uploading a hexfile to chips loaded with
bootloaders implementing the stk500 protocol, all you have to do is select you file and manually reset your
chip, wait for the 3 blinks indicating your bootloader is ready and hit the load firmware button.
Additional Windows Resources:

For those drawn to a CLI: Browse to the directory where you new hex files resides and enter the following
command (replace COM3 with your actual COM number):
avrdude -p m328p -D -PCOM3 -c arduino -b 115200 -U flash:w:grbl.hex

For Linux:
avrdude -v -patmega328p -Uflash:w:grbl_v0_9j_atmega328p_16mhz_115200.hex:i -carduino -b
57600 -P /dev/ttyUSBX

Last updated: 2012-01-30 by Atrixium. (Tested on Linux Mint 9 (Ubuntu 10.04) and the Arduino Uno and
IDE V1.0)
The tools for flashing grbl to an Arduino (called AVRDUDE) are included with the Arduino IDE software.
The following instructions have been tested and work for the Arduino Uno. For others, your mileage may
vary.
Linux users can now use the Easy Flash script to simplify the process.
Note that in Linux all commands are Case Sensitive
On a typical install, the AVRDUDE tools can be found in: /home/$USER/arduino-1.0/hardware/tools/,
depending on where you placed the Arduino IDE, the /home/$USER part of the path may be different.
AVRDUDE has two files that we need to be aware of: avrdude and avrdude.conf. For simplicity, this
document will refer to these two files and their paths as $AVRPATH and $CONFPATH respectively.
Next we need to find the device path for your Arduino. Connect your Arduino to a USB port, then, from a
Terminal window, enter: dmesg. This will display a long list of text, the bottom of which should look
something like the following:
[ 3058.480208] usb 7-1: new full speed USB device using ohci_hcd and address 15
[ 3058.673379] usb 7-1: configuration #1 chosen from 1 choice
[ 3058.675293] cdc_acm 7-1:1.0: ttyACM0: USB ACM device

The part that says ttyACM0 is my Arduino, your Arduino should be similarly named but may be ttyACM1 or
ttyACM2, etc. depending on how many USB modem devices you have installed. When you've determined
the name, your Arduino device path should like something like this: /dev/ttyACM0. from here on we'll call
this path $DEVPATH. Depending on your version of linux, it may also be something like \dev\ttyUSB0, this
was the case for me running Ubuntu.
To Flash Grbl: Using the Terminal, first make sure you're in the same directory as the grbl.hex file you
want to flash to the Arduino, which we'll call $GRBLHEX. Then, type one of the following command lines
in to flash:
For IDE version 0023 and prior: $AVRPATH -C$CONFPATH -pm328p -cstk500v1 -P$DEVPATH -D
-Uflash:w:$GRBLHEX

Example: \home\rob\arduino-1.0\hardware\tools\avrdude -C\home\rob\arduino1.0\hardware\tools\avrdude.conf -pm328p -cstk500v1 -P\dev\ttyACM0 -D


-Uflash:w:grbl_0_7d_atmega328p_16mhz_9600.hex

For v1.0: $AVRPATH -C$CONFPATH -pm328p -carduino -P$DEVPATH -D -Uflash:w:$GRBLHEX


Example: \home\rob\arduino-1.0\hardware\tools\avrdude -C\home\rob\arduino1.0\hardware\tools\avrdude.conf -pm328p -carduino -P\dev\ttyACM0 -D
-Uflash:w:grbl_0_7d_atmega328p_16mhz_9600.hex

Note that the only change between the two versions is the change from -cstk500v1 and -carduino; the
stk500v1 programmer to the Arduino programmer. This programmer flag was updated in the v1.0 IDE. Also,
note if you are using a Duemilanove it may require you add the flag -b 57600 to manually set the baud rate.
This is similar to the instructions above in the Mac OS X section. If all goes according to plan, you should
see three sequential progress bars of reading, writing, and verifying and you're good to go!

To flash with USBASP: If you normally use Arduino IDE with the "Upload using programmer" option
Call avrdude but with the USBASP options set
/home/user/arduino-nightly/hardware/tools/avr/bin/avrdude -C/home/dgtlmoon/arduinonightly/hardware/tools/avr/etc/avrdude.conf -v -patmega328p -cusbasp -Pusb
-Uflash:w:./grbl_v0_9j_atmega328p_16mhz_115200.hex:i

Additional Linux Resources:

An easy linux flashing script by Atrixium

Common Flashing Errors


error "avrdude: stk500_recv(): programmer is not responding Problem uploading to board"
can present itself when your arduino UNO has a firmware <=3.3
workaround is to flash an updated bootloader using an ISP programmer.
to check your UNO firmware version:
go to File>Preferences>"show verbose output during"> Upload.
this issue is non-OS dependent.
see issue #760 for more

Connecting Grbl
Bertus Kruger edited this page on Jun 10 14 revisions

This wiki is intended to provide various instructions on how to connect to grbl in various ways. Please feel
free to contribute more up-to-date or alternative methods.

Grbl's Pins
Pin diagram for Grbl v0.8 and v0.9 with the traditional layout: (NOTE: The probe A5 pin is only
available in Grbl v0.9.)

For Grbl v0.9 with variable spindle PWM ENABLED: (NOTE: The Z-limit and the spindle enable pin
are swapped, because we had to access the hardware PWM on D11 for variable spindle PWM output to
work.) We are still updating this pin configuration at the moment by weighing future options. We'd like to
only change the pins once. Stay tuned!

First, to connect your stepper motors to Grbl, you'll need some stepper motor drivers to power the steppers
and connect your driver inputs to the Arduino controller pins. There are a number of drivers that can do this,
available as fully pre-built, partially pre-built, or completely DIY. There are some examples farther down the
page. The stepper drivers will need to share the stepper enable pin (D8) to their respective enable pins, while
the direction and step pulse pins (D2-D7) will need to be connected to their respective pins on the drivers.
Just make sure that all of your drivers and the Arduino share a common ground (star grounded with your
motor driver power). This is about all you'll need to get started.
Afterwards, once you decide that you're ready or would like to enable homing and/or hard limits, you'll need
to connect a normally-open limit switch to each of the limit pins (D9-D11). Homing and hard limits use the

same switches. These limit pins are already held high with an internal pull-up resistor, so all you have to do
is wire them to ground. So when you close a switch, the switch will pull the limit pin to ground. If you'd like
to have hard limit switches on both ends of travel of an axis, just wire two limit switches in parallel to the
axis limit pin and ground. Make sure you have the switches installed before attempting to perform a homing
cycle, and make sure you practice good wiring methods to minimize external electric noise on the input pins.
In Grbl v0.8 and later, there are pin-outs of the cycle start, feed hold, and reset runtime commands, so you
can have physical control buttons are your machine. Just like the limit pins, these pins are held high with an
internal pull-up resistor, so all you have to do is connect a normally-open switch to each pin and to ground.
Again make sure you practice good wiring methods to minimize external electric noise on the input pins.
If you have a desire or need for spindle or coolant control, Grbl will toggle these output pins (D12, D13, A3)
high or low, depending on the G-code commands you send to Grbl. With v0.9 and variable spindle PWM
enabled, the D11 pin will output a range of voltages from 0V to 5V depending the spindle speed G-code
command. 0V indicates spindle off in this case. Since these pins are all application dependent in how they
are used, we'll leave it to you to determine how to control and use these for your machine. You can also hack
the spindle and coolant control source files to easily alter how they work and then compile and upload your
modified Grbl through the Arduino IDE.

Method One: EasyDriver V4.4


Last Updated: 2012-01-29 by Atrixium.
This is a fairly straightforward interface for a 3 axis machine.
The 'step signal ground' for each EasyDriver is connected together and tied to the GND pin of the Arduino.
Do not confuse this with the motor ground or any other ground connection on the EasyDriver!
The 'Step' pin for the X,Y and Z axes is attached to digital pins 2, 3 and 4 respectively.
The 'Dir' pin for the X,Y and Z axes is attached to digital pins 5, 6 and 7 respectively.

Resources
Big Version
Fritzing File
EasyDriver Website

Method Two: grblshield


Last Updated: 2012-02-21 by aldenhart.
grblshield - plugs on to Arduino for 3 axes of motor control - up to 2.5 amps per winding. Drivers are
thermally protected against overcurrent and are therefore extremely resistant to burnout or failure.

Method Three: stepper shield


Last Updated: 2012-02-03 by edwardrford.

buildlog.net arduino stepper shield - pololu driver carrier arduino shield for 3 axes of motor control.
Replaceable drivers in case of damage.
user guide

Method Four : Arduino CNC Shield or Raspberry Pi CNC Board/Hat


Last Updated: 2016-06-10 by Protoneer.
Arduino CNC Shield - 3 independent axes and one clone axis.Uses Pololu Stepper Drivers with all GRBL
pins exposed. GRBL 0.9 Compatible. RC filters on end stops and Probe pins.
Raspberry Pi CNC board/hat - 3 independent axes + 1 clonable drive and with removable screw
terminals.Uses Pololu Stepper Drivers with all GRBL pins exposed. GRBL 0.9 Compatible. RC filters on
end stops and Probe pins.

NOT SUPPORTED: H-bridge drivers.


Some early work on supporting this can be found here. It is out-dated and uses Grbl v0.7.

Other Resources:

DANK Last updated 2/2011.

Connecting Grbl to an H-bridge Driver

Configuring Grbl v0.9


David the Swarfer edited this page on Jul 28 26 revisions
Pages 14

Home

Compiling Grbl

Configuring Grbl v0.7

Configuring Grbl v0.8

Configuring Grbl v0.9

Connecting Grbl

Development Path and Future Needs

Flashing Grbl to an Arduino

Frequently Asked Questions

G Code Examples

Interfacing with Grbl

Known Bugs

Licensing

Using Grbl

Clone this wiki locally


https://githu

Clone in Desktop
Quick-Links:

Getting Started

Grbl Settings

Grbl's Settings and What They Mean

Grbl's Other $ Commands

Real-Time Commands

Getting Started
First, connect to Grbl using the serial terminal of your choice.
Set the baud rate to 115200 as 8-N-1 (8-bits, no parity, and 1-stop bit.)
Once connected you should get the Grbl-prompt, which looks like this:
Grbl 0.9i ['$' for help]

Type $ and press enter to have Grbl print a help message. You should not see any local echo of the $ and
enter. Grbl should respond with:
$$ (view Grbl settings)
$# (view # parameters)
$G (view parser state)
$I (view build info)
$N (view startup blocks)
$x=value (save Grbl setting)
$Nx=line (save startup block)
$C (check gcode mode)
$X (kill alarm lock)
$H (run homing cycle)
~ (cycle start)
! (feed hold)
? (current status)
ctrl-x (reset Grbl)

The $-commands are Grbl system commands used to tweak the settings, view or change Grbl's states and
running modes, and start a homing cycle. The last four non-'$' commands are realtime control commands
that can be sent at anytime, no matter what Grbl is doing. These either immediately change Grbl's running
behavior or immediately print a report of the important realtime data like current position (aka DRO).

Grbl Settings
$$ - 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.
$0=10 (step pulse, usec)
$1=25 (step idle delay, msec)
$2=0 (step port invert mask:00000000)
$3=6 (dir port invert mask:00000110)
$4=0 (step enable invert, bool)
$5=0 (limit pins invert, bool)
$6=0 (probe pin invert, bool)
$10=3 (status report mask:00000011)
$11=0.020 (junction deviation, mm)
$12=0.002 (arc tolerance, mm)
$13=0 (report inches, bool)
$20=0 (soft limits, bool)
$21=0 (hard limits, bool)
$22=0 (homing cycle, bool)
$23=1 (homing dir invert mask:00000001)
$24=50.000 (homing feed, mm/min)
$25=635.000 (homing seek, mm/min)
$26=250 (homing debounce, msec)
$27=1.000 (homing pull-off, mm)
$100=314.961 (x, step/mm)
$101=314.961 (y, step/mm)
$102=314.961 (z, step/mm)
$110=635.000 (x max rate, mm/min)
$111=635.000 (y max rate, mm/min)
$112=635.000 (z max rate, mm/min)
$120=50.000 (x accel, mm/sec^2)
$121=50.000 (y accel, mm/sec^2)
$122=50.000 (z accel, mm/sec^2)
$130=225.000 (x max travel, mm)
$131=125.000 (y max travel, mm)
$132=170.000 (z max travel, mm)

$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, but most Grbl GUIs will do this for you as a
user-friendly feature.
To manually change e.g. the microseconds step pulse option to 10us you would type this, followed by an
enter:
$0=10

If everything went well, Grbl will respond with an 'ok' and this setting is stored in EEPROM and will be
retained forever or until you change them. You can check if Grbl has received and stored your setting
correctly by typing $$ to view the system settings again.

Grbl's

$x=val

settings and what they mean

NOTE: Settings numbering has changed since v0.8c for future-proofing purposes.
$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, msec

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 255 milliseconds. Again, just to repeat, you can keep all axes always enabled by setting
$1=255.
The stepper idle lock time is the time length Grbl will keep the steppers locked before disabling. Depending
on the system, you can set this to zero and disable it. On others, 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. Also, 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:binary

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. Most
users will not need to use this setting, but this can be useful for certain CNC-stepper drivers that have
peculiar requirements. For example, an artificial delay between the direction pin and step pulse can be
created by inverting the step pin.
This invert mask setting is a value which stores the axes to invert as bit flags. You really don't need to
completely understand how it works. You simply need to enter the settings value for the axes you want to
invert. For example, if you want to invert the X and Z axes, you'd send $2=5 to Grbl and the setting should
now read $2=5 (step port invert mask:00000101).
Setting Value

Mask

Invert X

Invert Y

Invert Z

00000000

00000001

00000010

00000011

00000100

00000101

00000110

00000111

$3 Direction port invert mask:binary

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. Often,
axes don't move this way with some machines. This setting will invert the direction pin signal for those 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, bool

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, bool

By default, 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. Disable with $5=0. You may need a power cycle to load the change.
NOTE: If you invert your limit pins, you will need an external pull-down resistor wired in to all of the limit
pins to prevent overloading the pins with current and frying them.
$6 - Probe pin invert, bool

By default, 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. Disable with $6=0. You may need a power cycle to load the change.
NOTE: If you invert your probe pin, you will need an external pull-down resistor wired in to the probe pin
to prevent overloading it with current and frying it.
$10 - Status report mask:binary

This setting determines what Grbl real-time data it reports back to the user when a '?' status report is sent. By
default, Grbl will send back its running state (can't be turned off), machine position, and work position
(machine position with coordinate offsets and other offsets applied). Three additional reporting features are
available that are useful for interfaces or users setting up their machines, which include the serial RX buffer,
planner block buffer usage, and limit pin states (as high or low, shown in the order ZYX).
To set them, use the table below to determine what data you'd like Grbl to send back. Select the report types
you'd like to see in the status reports and add their values together. This is the value you use to send to Grbl.
For example, if you need machine and work positions, add the values 1 and 2 and send Grbl $10=3 to set it.
Or, if you need machine position only and limit pin state, add the values 1 and 16 and send Grbl $10=17.
In general, keep this real-time status data to a minimum, since it takes resources to print and send this data
back at a high rate. For example, limit pins reporting is generally only needed when users are setting up their
machine. Afterwards, it's recommended to disable it, as it isn't very useful once you've got everything
figured out.
Report Type

Value

Machine Position

Work Position

Planner Buffer

RX Buffer

Limit Pins

16

$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, bool

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, it is set to report in mm,
but by sending a $13=1 command, you send this boolean flag to true and these reporting features will now
report in inches. $13=0 to set back to mm.
$20 - Soft limits, bool

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, bool

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.) We strongly advise taking electric interference prevention measures. If you want a limit for
both ends of travel of one axes, just wire in two switches in parallel with the pin and ground, so if either one
of them trips, it triggers the hard limit.
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. Remember it's a purely a safety feature.
$22 - Homing cycle, bool

Ahh, homing. For those just initiated into CNC, 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. Say you start machining something or
are about to start the next step in a job and the power goes out, you re-start Grbl and Grbl has no idea where
it is. You're left with the task of figuring out where you are. If you have homing, you always have the
machine zero reference point to locate from, so all you have to do is run the homing cycle and resume where
you left off.
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 and ground, just like with the hard
limits, 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.
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) but more on that later.
Most, if not all CNC controllers, do something similar, as it is mostly a safety feature to prevent users from
making a positioning mistake, which is very easy to do and be saddened when a mistake ruins a part. If you
find this annoying or find any weird bugs, please let us know and we'll try to work on it so everyone is
happy. :)
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, int:binary

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, 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, ms

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.
$100, $101 and $102 [X,Y,Z] steps/mm

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. This is dependent on your belt
drive gears or lead screw pitch.

The full steps per revolution of your steppers (typically 200)

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 and $112 [X,Y,Z] Max rate, mm/min

This sets the 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 [X,Y,Z] Acceleration, mm/sec^2

This sets the axes acceleration parameters 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 feedrates 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 [X,Y,Z] Max travel, mm

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.

Grbl's Other '$' Commands


The other $ commands provide additional controls for the user, such as printing feedback on the current Gcode parser modal state or running the homing cycle. This section explains what these commands are and
how to use them.
$# - View gcode parameters

G-code parameters store the coordinate offset values for G54-G59 work coordinates, G28/G30 pre-defined
positions, G92 coordinate offset, tool length offsets, and probing (not officially, but we added here anyway).
Most of these parameters are directly written to EEPROM anytime they are changed and are persistent.
Meaning that they will remain the same, regardless of power-down, until they are explicitly changed. The
non-persistent parameters, which will are not retained when reset or power-cycled, are G92, G43.1 tool
length offsets, and the G38.2 probing data.
G54-G59 work coordinates can be changed via the G10 L2 Px or G10 L20 Px command defined by the
NIST gcode standard and the EMC2 (linuxcnc.org) standard. G28/G30 pre-defined positions can be changed
via the G28.1 and the G30.1 commands, respectively.
When $# is called, Grbl will respond with the stored offsets from machine coordinates for each system as
follows. TLO denotes tool length offset, and PRB denotes the coordinates of the last probing cycle.
[G54:4.000,0.000,0.000]
[G55:4.000,6.000,7.000]
[G56:0.000,0.000,0.000]
[G57:0.000,0.000,0.000]
[G58:0.000,0.000,0.000]
[G59:0.000,0.000,0.000]
[G28:1.000,2.000,0.000]
[G30:4.000,6.000,0.000]
[G92:0.000,0.000,0.000]
[TLO:0.000,0.000,0.000]
[PRB:0.000,0.000,0.000]
$G - View gcode parser state

This command prints all of the active gcode modes in Grbl's G-code parser. When sending this command to
Grbl, it will reply with something like:
[G0 G54 G17 G21 G90 G94 M0 M5 M9 T0 S0.0 F500.0]

These active modes determine how the next G-code block or command will be interpreted by Grbl's G-code
parser. For those new to G-code and CNC machining, modes sets the parser into a particular state so you
don't have to constantly tell the parser how to parse it. These modes are organized into sets called "modal

groups" that cannot be logically active at the same time. For example, the units modal group sets whether
your G-code program is interpreted in inches or in millimeters.
A short list of the modal groups, supported by Grbl, is shown below, but more complete and detailed
descriptions can be found at LinuxCNC's website. The G-code commands in bold indicate the default modes
upon powering-up Grbl or resetting it.
Modal Group Meaning

Member Words

Motion Mode

G0, G1, G2, G3, G38.2, G38.3, G38.4, G38.5, G80

Coordinate System Select

G54, G55, G56, G57, G58, G59

Plane Select

G17, G18, G19

Distance Mode

G90, G91

Arc IJK Distance Mode

G91.1

Feed Rate Mode

G93, G94

Units Mode

G20, G21

Cutter Radius Compensation

G40

Tool Length Offset

G43.1, G49

Program Mode

M0, M1, M2, M30

Spindle State

M3, M4, M5

Coolant State

M7, M8, M9

In addition to the G-code parser modes, Grbl will report the active T tool number, S spindle speed, and F
feed rate, which all default to 0 upon a reset. For those that are curious, these don't quite fit into nice modal
groups, but are just as important for determining the parser state.
$I - View build info

This prints feedback to the user the Grbl version and source code build date. Optionally, $I can also store a
short string to help identify which CNC machine you are communicating with, if you have more than
machine using Grbl. To set this string, send Grbl $I=xxx, where xxx is your customization string that is less
than 80 characters. The next time you query Grbl with a $I view build info, Grbl will print this string after
the version and build date.
$N - View startup blocks

are the startup blocks that Grbl runs every time you power on Grbl or reset Grbl. In other words, a
startup block is a line of G-code that you can have Grbl auto-magically run to set your G-code modal
defaults, or anything else you need Grbl to do everytime you start up your machine. Grbl can store two
blocks of G-code as a system default.
$Nx

So, when connected to Grbl, type $N and then enter. Grbl should respond with something short like:
$N0=
$N1=
ok

Not much to go on, but this just means that there is no G-code block stored in line $N0 for Grbl to run upon
startup. $N1 is the next line to be run.

$Nx=line - Save startup block

IMPORTANT: Be very careful when storing any motion (G0/1,G2/3,G28/30) commands in the startup
blocks. These motion commands will run everytime you reset or power up Grbl, so if you have an
emergency situation and have to e-stop and reset, a startup block move can and will likely make
things worse quickly. Also, do not place any commands that save data to EEPROM, such as
G10/G28.1/G30.1. This will cause Grbl to constantly re-write this data upon every startup and reset,
which will eventually wear out your Arduino's EEPROM.
Typical usage for a startup block is simply to set your preferred modal states, such as G20 inches
mode, always default to a different work coordinate system, or, to provide a way for a user to run
some user-written unique feature that they need for their crazy project.
To set a startup block, type $N0= followed by a valid G-code block and an enter. Grbl will run the block to
check if it's valid and then reply with an ok or an error: to tell you if it's successful or something went
wrong. If there is an error, Grbl will not save it.
For example, say that you want to use your first startup block $N0 to set your G-code parser modes like G54
work coordinate, G20 inches mode, G17 XY-plane. You would type $N0=G20 G54 G17 with an enter and
you should see an 'ok' response. You can then check if it got stored by typing $N and you should now see a
response like $N0=G20G54G17.
Once you have a startup block stored in Grbl's EEPROM, everytime you startup or reset you will see your
startup block printed back to you and a response from Grbl to indicate if it ran okay. So for the previous
example, you'll see:
Grbl 0.9i ['$' for help]
G20G54G17ok

If you have multiple G-code startup blocks, they will print back to you in order upon every startup. And if
you'd like to clear one of the startup blocks, (e.g., block 0) type $N0= without anything following the equal
sign.
Also, if you have homing enabled, the startup blocks will execute immediately after the homing cycle, not at
startup.
$C - Check gcode mode

This toggles the Grbl's gcode parser to take all incoming blocks and process them completely, as it would in
normal operation, but it does not move any of the axes, ignores dwells, and powers off the spindle and
coolant. This is intended as a way to provide the user a way to check how their new G-code program fares
with Grbl's parser and monitor for any errors (and checks for soft limit violations, if enabled).
When toggled off, Grbl will perform an automatic soft-reset (^X). This is for two purposes. It simplifies the
code management a bit. But, it also prevents users from starting a job when their G-code modes are not what
they think they are. A system reset always gives the user a fresh, consistent start.
$X - Kill alarm lock

Grbl's alarm mode is a state when something has gone critically wrong, such as a hard limit or an abort
during a cycle, or if Grbl doesn't know its position. By default, if you have homing enabled and power-up
the Arduino, Grbl enters the alarm state, because it does not know its position. The alarm mode will lock all
G-code commands until the '$H' homing cycle has been performed. Or if a user needs to override the alarm
lock to move their axes off their limit switches, for example, '$X' kill alarm lock will override the locks and
allow G-code functions to work again.

But, tread carefully!! This should only be used in emergency situations. The position has likely been lost,
and Grbl may not be where you think it is. So, it's advised to use G91 incremental mode to make short
moves. Then, perform a homing cycle or reset immediately afterwards.
$H - Run homing cycle

This command is the only way to perform the homing cycle in Grbl. Some other motion controllers
designate a special G-code command to run a homing cycle, but this is incorrect according to the G-code
standards. Homing is a completely separate command handled by the controller.
TIP: After running a homing cycle, rather jogging manually all the time to a position in the middle of your
workspace volume. You can set a G28 or G30 pre-defined position to be your post-homing position, closer
to where you'll be machining. To set these, you'll first need to jog your machine to where you would want it
to move to after homing. Type G28.1 (or G30.1) to have Grbl store that position. So then after '$H' homing,
you could just enter 'G28' (or 'G30') and it'll move there auto-magically. In general, I would just move the
XY axis to the center and leave the Z-axis up. This ensures that there isn't a chance the tool in the spindle
will interfere and that it doesn't catch on anything.
$RST=$, $RST=#, and $RST=*- Restore Grbl settings and data to defaults

These commands are not listed in the main Grbl $ help message, but are available to allow users to restore
parts of or all of Grbl's EEPROM data. Note: Grbl will automatically reset after executing one of these
commands to ensure the system is initialized correctly.

$RST=$ : Erases and restores the $$ Grbl settings back to defaults, which is defined by

the default settings file used when compiling Grbl. Often OEMs will build their Grbl
firmwares with their machine-specific recommended settings. This provides users and
OEMs a quick way to get back to square-one, if something went awry or if a user wants
to start over.

$RST=# : Erases and zeros all G54-G59 work coordinate offsets and G28/30 positions
stored in EEPROM. These are generally the values seen in the $# parameters printout.

This provides an easy way to clear these without having to do it manually for each set
with a G20 L2/20 or G28.1/30.1 command.

$RST=* : This clears and restores all of the EEPROM data used by Grbl. This includes $$
settings, $# parameters, $N startup lines, and $I build info string. Note that this doesn't

wipe the entire EEPROM, only the data areas Grbl uses. To do a complete wipe, please
use the Arduino IDE's EEPROM clear example project.

Real-Time Commands:

~, !, ?, and Ctrl-X

The last four of Grbl's commands are real-time commands. This means that they can be sent at anytime,
anywhere, and Grbl will immediately respond, no matter what it's doing. For those that are curious, these are
special characters that are 'picked-off' from the incoming serial stream and will tell Grbl to execute them,
usually within a few milliseconds.
~ - Cycle start

This is the cycle start or resume command that can be issued at any time, as it is a real-time command. When
Grbl has motions queued in its buffer and is ready to go, the ~ cycle start command will start executing the
buffer and Grbl will begin moving the axes. However, by default, auto-cycle start is enabled, so new users
will not need this command unless a feed hold is performed. When a feed hold is executed, cycle start will
resume the program. Cycle start will only be effective when there are motions in the buffer ready to go and
will not work with any other process like homing.

! - Feed hold

The feed hold command will bring the active cycle to a stop via a controlled deceleration, so as not to lose
position. It is also real-time and may be activated at any time. Once finished or paused, Grbl will wait until a
cycle start command is issued to resume the program. Feed hold can only pause a cycle and will not affect
homing or any other process.
If you need to stop a cycle mid-program and can't afford losing position, perform a feed hold to have Grbl
bring everything to a controlled stop. Once finished, you can then issue a reset. Always try to execute a feed
hold whenever the machine is running before hitting reset, except of course if there is some emergency
situation.
? - Current status

The ? command immediately returns Grbl's active state and the real-time current position, both in machine
coordinates and work coordinates. Optionally, you can also have Grbl respond back with the RX serial
buffer and planner buffer usage via the status report mask setting. The ? command may be sent at any time
and works asynchronously with all other processes that Grbl is doing. The $13 Grbl setting determines
whether it reports millimeters or inches. When ? is pressed, Grbl will immediately reply with something like
the following:
<Idle,MPos:5.529,0.560,7.000,WPos:1.529,-5.440,-0.000>

The active states Grbl can be in are: Idle, Run, Hold, Door, Home, Alarm, Check

Idle: All systems are go, no motions queued, and it's ready for anything.

Run: Indicates a cycle is running.

Hold: A feed hold is in process of executing, or slowing down to a stop. After the hold is
complete, Grbl will remain in Hold and wait for a cycle start to resume the program.

Door: (New in v0.9i) This compile-option causes Grbl to feed hold, shut-down the
spindle and coolant, and wait until the door switch has been closed and the user has
issued a cycle start. Useful for OEM that need safety doors.

Home: In the middle of a homing cycle. NOTE: Positions are not updated live during the
homing cycle, but they'll be set to the home position once done.

Alarm: This indicates something has gone wrong or Grbl doesn't know its position. This
state locks out all G-code commands, but allows you to interact with Grbl's settings if
you need to. '$X' kill alarm lock releases this state and puts Grbl in the Idle state, which
will let you move things again. As said before, be cautious of what you are doing after
an alarm.

Check: Grbl is in check G-code mode. It will process and respond to all G-code
commands, but not motion or turn on anything. Once toggled off with another '$C'
command, Grbl will reset itself.

Ctrl-x - Reset Grbl

This is Grbl's soft reset command. It's real-time and can be sent at any time. As the name implies, it resets
Grbl, but in a controlled way, retains your machine position, and all is done without powering down your
Arduino. The only times a soft-reset could lose position is when problems arise and the steppers were killed
while they were moving. If so, it will report if Grbl's tracking of the machine position has been lost. This is
because an uncontrolled deceleration can lead to lost steps, and Grbl has no feedback to how much it lost
(this is the problem with steppers in general). Otherwise, Grbl will just re-initialize, run the startup lines, and
continue on its merry way.

Please note that it's recommended to do a soft-reset before starting a job. This guarantees that there aren't
any G-code modes active that from playing around or setting up your machine before running the job. So,
your machine will always starts fresh and consistently, and your machine does what you expect it to.

Configuring Grbl v0.8


Karel Heyse edited this page on Jan 4 2014 26 revisions

Grbl has a system $-command to tweak the settings and trigger runtime commands. Connect to Grbl using
the serial terminal of your choice (baud rate 9600 unless you changed that in config.h) as 8-N-1 (8-bits, no
parity, and 1-stop bit.) Once connected you should get the Grbl-prompt, which looks like this:
Grbl 0.8c ['$' for help]

Type $ and press enter. You should not see any local echo of the $ and enter, but Grbl should respond with a
help message:
$$ (view Grbl settings)
$# (view # parameters)
$G (view parser state)
$N (view startup blocks)
$x=value (save Grbl setting)
$Nx=line (save startup block)
$C (check gcode mode)
$X (kill alarm lock)
$H (run homing cycle)
~ (cycle start)
! (feed hold)
? (current status)
ctrl-x (reset Grbl)

Of these commands, only four of them are used to configure Grbl [$$, $x=value, $N, $Nx=line], while
the rest are runtime commands that either report the current state in Grbl or tweak the behavior.

The four configuration commands:

$$, $x=val, $N, $Nx=line

$$ - View Grbl settings, $x=val - Save Grbl setting

When connected to Grbl, type $$ and press enter. Grbl should respond with a list of the current system
settings, similar to as shown in the following. All of these settings are persistent and kept in EEPROM, so if
you power down, these will be loaded back up the next time your power up your Arduino.
$0=755.906 (x, step/mm)
$1=755.906 (y, step/mm)
$2=755.906 (z, step/mm)
$3=30 (step pulse, usec)
$4=500.000 (default feed, mm/min)
$5=500.000 (default seek, mm/min)
$6=28 (step port invert mask, int:00011100)
$7=25 (step idle delay, msec)
$8=50.000 (acceleration, 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=0 (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)

To change e.g. the microseconds step pulse option to 10us you would type this, followed by an enter:
$3=10

If everything went well, Grbl will respond with an 'ok' and this setting is stored in EEPROM and will be
retained forever or until you change them. You can check if Grbl has received and stored your setting
correctly by typing $$ to view the system settings again.
$N - View startup blocks, $Nx=line - Save startup block

are the startup blocks that Grbl runs everytime you power on Grbl or reset Grbl. In other words, a
startup block is a line of g-code that you can have Grbl auto-magically run to set your g-code defaults, or
anything else you need Grbl to do everytime you start up your machine. At the moment, Grbl will store two
blocks of g-code as a system default, but it can store anywhere from 1 to 5, as a compile-time option
(changing config.h and re-compiling).
$Nx

So, when connected to Grbl, type $N and then enter. Grbl should respond with something short like:
$N0=
$N1=
ok

Not much to go on, but this just means that there is no g-code block stored in line $N0 for Grbl to run upon
startup. $N1 is the next line to be run. (If you re-compile to have more, it will execute in order on to $N4.)
To set a startup block, type $N0= followed by a valid g-code block and an enter. Grbl will run the block to
check if it's valid and then reply with an ok or an error: to tell you if it's successful or something went
wrong.
For example, say that you want to use your first startup block $N0 to set your g-code parser modes like G54
work coordinate, G20 inches mode, G17 XY-plane. You would type $N0=G20 G54 G17 with an enter and
you should see an 'ok' response. You can then check if it got stored by typing $N and you should now see a
response like $N0=G20G54G17.
Once you have a startup block stored in Grbl's EEPROM, everytime you startup or reset you will see your
startup block printed back to you and a response from Grbl to indicate if it ran ok. So for the previous
example, you'll see:
Grbl 0.8c ['$' for help]
G20G54G17ok

If you have multiple g-code startup blocks, they will print back to you in order upon every startup. And if
you'd like to clear one of the startup blocks, type $N0= without anything following the equal sign.
Also, if you have homing enabled, the startup blocks will execute immediately after the homing cycle, not at
startup.
IMPORTANT: Be very careful when storing any motion (G0/1,G2/3,G28/30) commands in the startup
blocks. These motion commands will run everytime you reset or power up Grbl, so if you have an
emergency situation and have to e-stop and reset, a startup block move can and will likely make things
worse quickly.

Grbl's

$x=val

settings and what they mean

$0, $1 and $2 XYZ, steps/mm

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 per revolution of the lead screw

The full steps per revolution of your steppers (typically 200)

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 axes 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.
$3 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 as short pulses as the stepper drivers can reliably recognize. If the pulses are too long
you might run into trouble running the system at high feed rates. Generally something between 5 and 50
microseconds works fine.
$4 and $5 Default feed and seek rates, mm/min

This setting sets the default seek(G0) and feed rates(G1,G2,G3) after Grbl powers on and initializes. The
seek rate (aka rapids) is used for moving from point A to point B as quickly as possible, usually for
traversing into position. The seek rate should be set at the maximum speed your machine can go in any axes
movement. The default feed rate usually does not enter into the picture as feed rates will generally be
specified in the g-code program, but if not, this default feed rate will be used.
NOTE: In future releases, the default feed rate will be removed. G-code standards do not have a default feed
rate (G1,G2,G3), but error out if there has been no 'F' feed rate command specified. The seek rate (aka
rapids) will be updated so users can specify the maximum speed each axes can move, rather than have just
one speed that limits all of them.
$6 Step port invert mask, int:binary

Some cnc-stepper controllers needs its high-low inputs inverted for both direction and steps. Signal lines are
normally held high or low to signal direction or held high and goes low for a couple of microseconds to
signal a step event. To achieve this, Grbl can invert the output bits to accomodate particular needs. The
invert mask value is a byte that is xored with the step and direction data before it is sent down the stepping
port. That way you can use this both to invert step pulses or to invert one or more of the directions of the
axes. The bits in this byte corresponds to the pins assigned to stepping in config.h. Note that bits 0 and 1 are
not used for inversion. Per default bits are assigned like this:
#define
#define
#define
#define
#define
#define

X_STEP_BIT 2
Y_STEP_BIT 3
Z_STEP_BIT 4
X_DIRECTION_BIT 5
Y_DIRECTION_BIT 6
Z_DIRECTION_BIT 7

If you wanted to invert the X and Y direction in this setup you would calculate a value by bitshifting like this
(in your favorite calculating environment):
> (1<<X_DIRECTION_BIT)|(1<<Y_DIRECTION_BIT)

Which is equal to 96, so issuing this command would invert them:

$6=96

Now when you view the current settings, you should now see this in your invert mask line with the binary
representation of the number (bits 5 and 6 should now show a 1 to indicate inversion.)
$6=96 (step port invert mask. int:1100000)

$7 - Step idle delay, msec

Every time your steppers complete a motion and come to a stop, Grbl will disable the steppers by default.
The stepper idle lock time is the time length Grbl will keep the steppers locked before disabling. Depending
on the system, you can set this to zero and disable it. On others, you may need 25-50 milliseconds to make
sure your axes come to complete stop before disabling. (My machine tends to drift just slightly if I don't
have this enabled.) OR, you can always keep your axes enabled at all times by setting this value to the
maximum 255 milliseconds. Again, just to repeat, you can keep all axes always enabled by setting $7=255.
$8 Acceleration, mm/sec^2

This is the acceleration in mm/second/second. You dont have to understand what that means, suffice it to
say that a lower value gives smooooother acceleration while a higher value yields tighter moves and reach
the desired feedrates much quicker. In technical terms, this is the point to point acceleration of your
machine, independent of axes. Set this acceleration value as high as your most limiting axes can let you
without losing ANY steps. Usually you'd like to give yourself a little buffer, because if you lose steps, Grbl
has no idea this has happened (steppers are open-loop control) and will keep going.
$9 Junction deviation, mm

Cornering junction deviation is used by the acceleration manager to determine how fast it can move through
a path. The math is a bit complicated but in general, higher values gives generally faster, possibly jerkier
motion. 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. If you want your machine to move faster through junctions, increase this value to
speed it up. For technical 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.
$10 Arc, mm/segment

Grbl renders circles and arcs by subdividing them into teeny tiny lines. You will probably never need to
adjust this value but if you find that your circles are too crude (really? one tenth of a millimeter is not
precise enough for you? Are you in nanotech?) you may adjust this. Lower values gives higher precision but
may lead to performance issues.
$11 - N-arc correction, int

This is an advanced setting that shouldn't be changed unless there are circumstances that you need to. To
make G02/03 arcs possible in Grbl, Grbl approximates the location of the next arc segment by a small angle
approximation. N-arc correction is the number of approximate arc segments performed before Grbl
computes an exact arc segment to correct for the approximation error drift. Computing these exact locations
are computationally expensive, but there are some extreme cases where the small angle approximations can
introduce enough error to be noticeable, like very very small arcs with a large arc segment length. Change
this setting only if find strange problems with arcs, but it's not recommended to go below 3 because this may
lead to buffer starvation, where the axes slow down and hiccup. But, results can vary.
$12 - N-decimal, int

Set how many decimal places all of the floating point values Grbl reports. Not much more complicated than
that.
$13 - Report inches, bool

Grbl v0.8 has a real-time positioning reporting feature to provide a user feedback on where the machine is
exactly at that time. By default it is set to report in mm, but by sending a $13=1 command, you send this
boolean flag to true and the status reporting feature will now report in inches. $13=0 to set back to mm.
$14 - Auto start, bool

In a more professional CNC environment, pros start a job by loading up their program and then pressing the
'cycle start' button on their machine. It begins the job. Grbl does the same thing, but not by default. As a
learning tool, we 'auto-cycle start' any g-code command that user sends to Grbl, for just jogging the machine
to see if move in the direction they think it should go, or just seeing with what their machine can do. This
makes it easier to load up your machine with Grbl and pick up on how it works, rather than having to
diligently hit 'cycle start' anytime you want to move any your axes. Once you learn your machine and get a
good handle on g-code, you can disable the 'auto cycle-start' feature by sending Grbl $14=0 command. (May
need a soft-reset or power cycle to load the change.)
Another way of saying that might be:
If $14=0 then some gcode commands like Xn, Yn etc. won't happen when you enter them at a serial
terminal. If $14=1 then the gcode motion commands will happen.
Apparently big cnc's won't execute gcode until the operator presses a 'cycle start' button. The gcode
commands were received but queued and awaiting the 'cycle start' button. Makes sense yes? When $14=0
then that's how grbl acts too. You need the button! (in which case attach the feed-hold button too!).
When $14=1 then the grbl software automatically presses a software version of the 'cycle start' for you each
time you 'enter' a gcode command line via a serial terminal. This is done to make it more convenient for you
to enter commands and see something happen without having to push the button.
$15 - Invert step enable, bool

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 $15=1. Disable with $15=0. (May need a power cycle to load the
change.)
$16 - Hard limits, bool

Hard limit switches are a safety feature to help prevent your machine from traveling way too far off the ends
of travel and crashing or breaking something expensive. Basically you wire up some switches (mechanical
or optical) near the end of travel of each axes, or where ever you feel like there might be trouble if your
program moves too far to where it shouldn't. When the switch triggers, it will immediately stop 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 $16=1. That's it.
(Disable with $16=0) If you want a limit for both ends of travel of one axes, just wire in two switches in
parallel with the pin and ground, so if either one of them trips, it triggers the hard limit.

Just know, that a hard limit event is considered to be critical event, where steppers immediately stop and will
have likely 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. Remember it's a purely a safety feature.
If you have issues with the hard limit switch constantly triggering after you reset, a soft-reset will reset Grbl
into an alarm state, where you can access the settings and Grbl commands, but all g-codes and startup blocks
will be locked out. So you can disable the hard limits setting and then $X unlock the alarm. Or, you can wire
in a normally-closed switch in series with ground to all the limit switches to disconnect the switches
temporarily so you can have Grbl move your axes off the switches.
$17 - Homing cycle, bool

Ahh, homing. Something that has been sorely needed in Grbl for a long time. It's now fully supported in
v0.8. For those just initiated into CNC, the homing cycle is used to accurately and precisely locate position
zero on a machine (aka machine zero) everytime you startup your Grbl between sessions. In other words,
you know exactly where you are at any given time, every time. Say you start machining something or are
about to start the next step in a job and the power goes out, you re-start Grbl and Grbl has no idea where it
is. You're left with the task of figuring out where you are. If you have homing, you always have the machine
zero reference point to locate from, so all you have to do is run the homing cycle and resume where you left
off.
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 and ground, just like with the hard
limits, 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.
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) but more on that later.
Most, if not all CNC controllers, do something similar, as it mostly a safety feature to help users from
making positioning mistake, which is very easy to do and be saddening when a mistake ruins a part. If you
find this annoying or find any weird bugs, please let us know and we'll try to work on it so everyone is
happy. :)
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.
$18 - Homing dir invert mask, int:binary

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 invert stepper mask, where all you have to do set
the axis direction pins to 1 that you want to invert and that axes will now search for the limit pin in the
negative direction.
$19 - Homing feed, mm/min

The homing cycle first searches for the limit switches at a higher seek rate, and after it finds them, it moves
at a slower feed rate to hone 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.
$20 - 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. This seek rate behaves a little differently than the main stepper driver.
Instead of the rate from point to point, it just moves all of the axes at the same individual rate, regardless of
how many axes are moving at the same time. So, the XY seek move will seem to move about 41% faster
than if you would move it with a G1 command. (You can disable this in config.h if it bothers you. It's there
to speed up the homing cycle.)
$21 - Homing debounce, ms

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.
$22 - 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 the 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.
The homing seek rate setting controls how quickly the pull-off maneuver moves, like a G1 command.

Grbl Internal Commands:


Technically, the remaining Grbl commands are not configuration commands, but we're going to explain
them here for no good reason, other than for completeness.

The three current state commands:

$G, $#, ?

Grbl provides three commands to report its current state and where it is. Of the three, one of them is realtime, responding with current position. The other two are not, but respond with how incoming blocks are
going to be processed depending on the states set by g-code, settings, or switches. The reason they are not
realtime is that Grbl has an internal buffer that stores and plans the buffered motions. The incoming gcode
blocks just tack on a new motion at the end of the buffer when it has room. The buffer basically ensures Grbl
motion move at the fastest and safest rates possible, constantly re-calculating it real-time as motions finish
and new ones come in.
$G - View gcode parser state

This command prints all of the active gcode modes that the parser will interpret any incoming command.
These modes include G20/G21 inches/mm mode, G54-G59 active work coordinate system, G0/G1/G2/G3
active motion mode, G17/G18/G19 active plane selection, G90/G91 absolute mode, G93/G94 inverse feed
rate mode, M0/M1/M2 program flow, M3/M4/M5 spindle state, M8/M9 coolant state, T tool number, and F
active feed rate. It will also list any active $Sx Grbl switches, like $S1 block delete. When called, Grbl will
return a line like this:

[G0 G54 G17 G21 G90 G94 M0 M5 M9 T0 F500.000]


$# - View gcode parameters

G-code parameters generally store the G54-G59 work coordinate offsets and G28/G30 home positions (must
not be confused with homing and machine zero. These home positions can be set anywhere in the machine
space by the G28.1/G30.1 commands). Most of these parameters are directly written to EEPROM anytime
they are changed and are persistent. Meaning that they will remain the same, regardless of power-down,
until they are explicitly changed.
G54-G59 work coordinates can be changed via the G10 L2 Px or G10 L20 Px command defined by the
NIST gcode standard and the EMC2 (linuxcnc.org) standard. G28/G30 home positions can be changed via
the G28.1 and the G30.1 commands, respectively. Please note that G92 is not persistent or held in EEPROM
per g-code standards, and will reset to zero when Grbl is reset. Please read these g-code standard to
understand how they are used.
When $# is called, Grbl will respond with the stored offsets from machine coordinates for each system as
follows.
[G54:4.000,0.000,0.000]
[G55:4.000,6.000,7.000]
[G56:0.000,0.000,0.000]
[G57:0.000,0.000,0.000]
[G58:0.000,0.000,0.000]
[G59:0.000,0.000,0.000]
[G28:1.000,2.000,0.000]
[G30:4.000,6.000,0.000]
[G92:0.000,0.000,0.000]

For the most part, these offset are not particularly useful unless you have homing enabled. If you do have
homing enabled, these are wonderfully awesome, because once you home, you can always move back to
same stored position by using the work coordinate systems within the accuracy of your machine. Or if you
are making multiple parts and have a tool path for just one part, all you have to do is setup your work
coordinate systems to the location where the next part is going to be made and re-run that same code.
? - Current status

The ? command immediately returns Grbl's active state and the real-time current position, both in machine
coordinates and work coordinates. This may be sent at any time and works asynchronously with all other
processes that Grbl is doing. The $13 Grbl setting determines whether it reports millimeters or inches. When
? is pressed, Grbl will immediately reply with something like the following:
<Idle,MPos:5.529,0.560,7.000,WPos:1.529,-5.440,-0.000>

The active states Grbl can be in are: Idle, Queue, Run, Hold, Home, Alarm, Check

Idle: All systems are go and it's ready for anything.

Queue: Motion(s) are queued in the planner buffer waiting for a cycle start command
to be issued. Certain processes like check g-code mode can't run while something is
queued. Reset to clear the queue.

Run: Indicates a cycle is running.

Hold: A feed hold is in process of executing, or slowing down to a stop. After the hold is
complete, Grbl will enter a Queue state, waiting for a cycle start to resume the
program.

Home: In the middle of a homing cycle. NOTE: Positions are not updated live during the
homing cycle, but they'll be set to [0,0,0] once done.

Alarm: This indicates something has gone wrong or Grbl doesn't know its position. This
state locks out all g-code commands, but allows you to interact with Grbl's settings if
you need to. '$X' kill alarm lock releases this state and puts Grbl in the Idle state, which
will let you move things again. As said before, be cautious of what you are doing after
an alarm.

Check: Grbl is in check g-code mode. It will process and respond to all g-code
commands, but not motion or turn on anything. Once toggled off with another '$C'
command, Grbl will reset itself.

Other Commands

$C $X $H ~ ! Ctrl-X

$C - Check gcode mode

This toggles the Grbl's gcode parser to take all incoming blocks process them completely, as it would in
normal operation, but it does not move any of the axes, ignores dwells, and powers off the spindle and
coolant. This is intended as a way to provide the user a way to check how their new g-code program fares
with Grbl's parser and monitor for any errors. (And eventually this will also check for soft limit violations.)
When toggled off, Grbl will perform an automatic soft-reset (^X). This is for two purposes. It simplifies the
code management a bit. But, it also prevents users from starting a job when their g-code modes are not what
they think they are. A system reset always gives the user a fresh, consistent start.
NOTE: Eventually, the check gcode mode could be re-factored to allow for a "program resume" feature in
Grbl. This means that Grbl could start a g-code program anywhere. It would internally go through all of the
g-code program up to the desired mid-program resume point to set all of the parser states and locations,
move to that start point, and begin executing/moving from that point on. For example, say you had to E-stop
in the middle of a program because you forgot something or you have the wrong tool in the spindle. Your
part is fine and need to restart the program. Right now, you'll have to start the program from the beginning
and let it physically move and run up to the point where you e-stopped. If you have a long program, this
could take a while. Instead, a "program resume" will just go through the beginning of the program internally,
without moving anything, and only begin moving from the resume point on.
$X - Kill alarm lock

Grbl's alarm mode is a state when something has gone critically wrong, like a hard limit or an abort during a
cycle, or if Grbl doesn't know its position. By default, if you have homing enabled and power-up the
Arduino, Grbl enters the alarm state, because it does not know its position. The alarm mode will lock all gcode blocks until the '$H' homing cycle has been performed. Or if a user needs to override the alarm lock to
move their axes off their limit switches, for example, '$X' kill alarm lock will override the locks and allow gcode functions to work again.
But, tread carefully!! This should only be used in emergency situations. The position has likely been lost,
and Grbl may not be where you think it is. So, it's advised to use G91 incremental mode to make short
moves. Then, perform a homing cycle or reset immediately afterwards.
$H - Run homing cycle

This command is the only way to perform the homing cycle in Grbl. Previously, G28 and G30 would
automatically start the homing cycle, but this is incorrect according to the g-code standards. Homing is a
completely separate command handled by the controller. G28 and G30 only move to a 'home'/pre-defined
position that is stored in the g-code parameters, which can be located anywhere in the machine.
TIP: After running a homing cycle, rather jogging manually all the time to a position in the middle of your
workspace volume. You can set a G28 or G30 pre-defined position to be your post-homing position, closer

to where you'll be machining. To set these, you'll first need to jog your machine to where you would want it
to move to after homing. Type G28.1 (or G30.1) to have Grbl store that position. So then after '$H' homing,
you could just enter 'G28' (or 'G30') and it'll move there auto-magically. In general, I would just move the
XY axis to the center and leave the Z-axis up. This ensures that there isn't a chance the tool in the spindle
doesn't catch on anything.
~ - Cycle start

This is the cycle start or resume command that can be issued at any time, as it is a real-time command. When
Grbl has motions queued in its buffer and is ready to go, the ~ cycle start command will start executing the
buffer and Grbl will begin moving the axes. However, by default, auto-cycle start is enabled, so new users
will not need this command unless a feed hold is performed. When a feed hold is executed, cycle start will
resume the program. Cycle start will only be effective when there are motions in the buffer ready to go and
will not work with any other process like homing.
! - Feed hold

The feed hold command will bring the active cycle to a stop via a controlled deceleration, so not to lose
position. It is also real-time and may be activated at any time. Once finished or paused, Grbl will wait until a
cycle start command is issued to resume to program. Feed hold can only pause a cycle and will not affect
homing or any other process.
If you need to stop a cycle mid-program and can't afford losing position, perform a feed hold to have Grbl
bring everything to a controlled stop. Once finished, you can then issue a reset. Always try to execute a feed
hold whenever the machine is running before hitting reset, except of course if there is some emergency
situation.
Ctrl-x - Reset Grbl

This is Grbl's soft reset command. It's real-time and can be sent at any time. As the name implies, it resets
Grbl, but in a controlled way, retains your machine position, and all done without powering down your
Arduino. The only times a soft-reset could lose position is when problems like if the steppers were killed
while they were moving. If so, it will report if Grbl's tracking of the machine position has been lost. This is
because an uncontrolled deceleration can lead to lost steps, and Grbl has no feedback to how much it lost
(this is the problem with steppers in general). Otherwise, Grbl will just re-initialize, run the startup lines, and
continue on its merry way.
Please note that it's recommended to do a soft-reset before starting a job. This guarantees that there aren't
any g-code modes active that should be from playing around or setting up your machine. So, your machine
will always starts fresh and consistently, and your machine does what you expect it to.

Configuring Grbl v0.7


chamnit edited this page on Mar 9 2013 3 revisions

Grbl has the neat $-command to tweak the settings at runtime. Connect to Grbl using the serial terminal of
your choice (baud rate 9600 unless you changed that in config.h) as 8-N-1 (8-bits, no parity, and 1-stop bit.)
Once connected you should get the Grbl-prompt, which looks like this:
Grbl v0.7
'$' to dump current settings

Type $ and press enter. You should not see any local echo of the $ and enter, but Grbl should respond with:
$0 = 400.0 (steps/mm x)
$1 = 400.0 (steps/mm y)
$2 = 400.0 (steps/mm z)

$3 = 30 (microseconds step pulse)


$4 = 480.0 (mm/sec default feed rate)
$5 = 480.0 (mm/sec default seek rate)
$6 = 0.100 (mm/arc segment)
$7 = 0 (step port invert mask. binary = 0)
$8 = 25 (acceleration in mm/sec^2)
$9 = 0.05 (cornering junction deviation in mm)
'$x=value' to set parameter or just '$' to dump current settings

To change e.g. the microseconds step pulse option to 50us you would type this, followed by an enter:
$3=50

If everything went well, Grbl will respond with an 'ok' and this setting is stored in eeprom and will be
retained forever or until you change them. You can check if Grbl has received and stored your setting
correctly by typing $ to view the system settings again.
$0, $1 and $2 Steps/mm

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 per revolution of the lead screw

The full steps per revolution of your steppers (typically 200)

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 axes 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.
$3 Microseconds/step pulse

Stepper drivers are rated for a certain minimum step pulse length. Check the data sheet or just try some
numbers. You want as short pulses as the stepper drivers can reliably recognize. If the pulses are too long
you might run into trouble running the system at high feed rates. Generally something between 20 and 50
microseconds works.
$4 and $5 Default seek and feed rates

This setting sets the default seek(G0) and feed rates(G1,G2,G3) after Grbl powers on and initializes. The
seek rate (aka rapids) is used for moving from point A to point B as quickly as possible, usually for
traversing into position or homing. The seek rate should be set at the maximum speed your machine can go
in any axes movement. The default feed rate usually does not enter into the picture as feed rates will
generally be specified in the g-code program, but if not, this default feed rate will be used.
$6 Mm/arc segment

Grbl renders circles and arcs by subdividing them into teeny tiny lines. You will probably never need to
adjust this value but if you find that your circles are too crude (really? one tenth of a millimeter is not
precise enough for you? Are you in nanotech?) you may adjust this. Lower values gives higher precision but
may lead to performance issues.
$7 invert mask

Some cnc-stepper controllers needs its high-low inputs inverted for both direction and steps. Signal lines are
normally held high or low to signal direction or held high and goes low for a couple of microseconds to
signal a step event. To achieve this, Grbl can invert the output bits to accomodate particular needs. The
invert mask value is a byte that is xored with the step and direction data before it is sent down the stepping
port. That way you can use this both to invert step pulses or to invert one or more of the directions of the
axes. The bits in this byte corresponds to the pins assigned to stepping in config.h. Note that bits 0 and 1 are
not used for inversion. Per default bits are assigned like this:
#define
#define
#define
#define
#define
#define

X_STEP_BIT 2
Y_STEP_BIT 3
Z_STEP_BIT 4
X_DIRECTION_BIT 5
Y_DIRECTION_BIT 6
Z_DIRECTION_BIT 7

If you wanted to invert the X and Y direction in this setup you would calculate a value by bitshifting like this
(in your favorite calculating environment):
> (1<<X_DIRECTION_BIT)|(1<<Y_DIRECTION_BIT)

Which is equal to 96, so issuing this command would invert them:


$7=96

Now when you view the current settings, you should now see this in your invert mask line with the binary
representation of the number (bits 5 and 6 should now show a 1 to indicate inversion.)
$7 = 96 (step port invert mask. binary = 1100000)

$8 Acceleration

This is the acceleration in mm/second/second. You dont have to understand what that means, suffice it to
say that a lower value gives smooooother acceleration while a higher value yields tighter moves and reach
the desired feedrates much quicker. In technical terms, this is the point to point acceleration of your
machine, independent of axes. Set this acceleration value as high as your most limiting axes can let you
without losing ANY steps. Usually you'd like to give yourself a little buffer, because if you lose steps, Grbl
has no idea this has happened (steppers are open-loop control) and will keep going.
$9 Cornering junction deviation in mm

Cornering junction deviation is used by the acceleration manager to determine how fast it can move through
a path. The math is a bit complicated but in general, higher values gives generally faster, possibly jerkier
motion. 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. If you want your machine to move faster through junctions, increase this value to
speed it up. For technical 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.

Using Grbl
Sonny Jeon edited this page 18 days ago 31 revisions

This wiki page is intended to provide various instructions on how to use Grbl. Please feel free to contribute
and help keep this page up-to-date!

Getting Started (For New Users.)


After flashing Grbl to your Arduino, connecting to Grbl is pretty simple. You can use the Arduino IDE itself
to connect to Grbl. Experiment or play with it, just to see if you like it. Other serial port programs, such as
CoolTerm or PuTTY, work great too. The instructions are pretty much the same.

Open up the Arduino IDE and make sure your Arduino with Grbl is connected to your
USB port.

Select the Arduino's Serial Port in the Tools menu, as you would normally with an
Arduino.

Open up the 'Serial Window' in the Tools menu.


o

If you are using Grbl v0.9, make sure to change the baud rate from 9600 to
115200.

Once open, you should see a Grbl welcome message like Grbl v0.Xx ['$' for help].
This means all is good! You're connected!
o

Make sure you change the "No line ending" drop-down menu to "Carriage
return". If you are using any other serial port program, you must do the same.

If you haven't received the welcome message or some garbled characters, make
sure that the baud rate is set at 9600 (or 115200 for v0.9+).

From here, you can simply start sending Grbl some G-code commands, and it'll perform them for you. Or,
you can type $ to get some help on what some of Grbl's special commands are or how to write some of your
machine settings into Grbl's EEPROM memory.
When have started to feel comfortable with G-code/CNC and you're ready to run a whole G-code program,
we recommend that you use one of the many great GUIs that users have written to stream your G-code
programs to Grbl and to fully harness all of Grbl's capabilities.
NOTE: Check out ShapeOko's Wiki. It has the most up-to-date and comprehensive list of Grbl GUIs.

How to Stream G-Code Programs to Grbl


bCNC

An advanced fully featured g-code sender for GRBL. bCNC is a cross platform program (Windows, Linux,
Mac) written in python with minimal external dependencies. The sender is robust and fast able to work
nicely with old or slow hardware like Rasperry PI (As it was validated by the GRBL mainter on heavy
testing).
Features:

simple and intuitive interface for small screens

importing g-code and dxf files

fast g-code sender (works nicely on RPi and old hardware)

workspace configuration (dialog for G54..G59 commands)

user configurable buttons

g-code function evaluation with run time expansion

Easy probing:

simple probing

center finder with a probing ring

auto leveling, Z-probing and auto leveling by altering the g-code during
sending.

height color map display

manual tool change expansion and automatic tool length probing

Various Tools:
o

user configurable database of materials, endmills, stock

properties database of materials, stock, end mills etc..

basic CAM features (profiling, pocketing, drilling)

User g-code plugins:

bowl generator

finger joint box generator

simple spur gear generator

spirograph generator

surface flatten

...

G-Code editor and display


o

graphical display of the g-code, and workspace

graphically moving and editing g-code

reordering code and rapid motion optimization

moving, rotating, mirroring the g-code

web pendant to be used via smart phones

Universal G-code Sender (UGS) [Java Cross-Platform]

A full-featured GUI, developed by @wwinder, that streams, visualizes G-code, and has complete control and
feedback functionality for Grbl's higher level features. It's written in Java, which means it can be run on any
Java-capable machine including the RaspberryPi! The Grbl group works closely with this project and highly
recommend using this GUI. If you find any issues or would like to request more GUI features, @wwinder
has done a wonderful job in completing many of the requests.

Easel [Browser-based CAD + CAM + Grbl controller]

Easel is a web based project developed by Inventables specifically for use with X-Carve, Carvey + Grbl. It is
an all-in-one package for design (including SVG imports), toolpath generation, and machine control. It also
has an app store where 3rd party developers can make apps that can import into Easel. Documentation for
how to make an app is here (https://discuss.inventables.com/c/easel/app-development). In addition to 2D
design tools, Easel lets you preview your toolpaths in 3D before sending them to your machine. You can also
import G-Code into Easel and use it as a sender. Easel is in constant development by the Inventables team.
You can request features or report issues through the feedback button in the app or on the Inventables forum
www.inventables.com/forum.

GRBLweb [Web Browser]

GRBLweb is a web based GCODE sender and controller for GRBL. Multiple serial devices can be
connected to control multiple machines.
There is also a pre-built Raspberry Pi image based on Raspbian running GRBLweb available here.

GrblPanel [Windows]

Maintained by retired computer professional @gerritv, GrblPanel is a GUI that implements more advanced
features and functionality commonly found in production machines like Haas, Fanuc, etc. All of the required
tools for setting up and running a milling job are neatly arranged and designed to be easily accessible based
on decades-old accepted workflows in machine shops. GrblPanel currently only works in Windows via .Net
v4.5, but will eventually be updated for cross-platform use through Mono.

grblControl [Windows/Linux]

GUI application for GRBL-based CNC-machines with G-Code visualizer.


Supported functions:

Controlling GRBL-based cnc-machine via console commands, buttons on form, numpad.

Monitoring cnc-machine state.

Loading, editing, saving and sending of G-code files to cnc-machine.

Visualizing G-code files.

Autoleveling Z-axis for PCB milling.

Python Streaming Scripts (Officially Supported by Grbl) [Cross-Platform]

NOTE: If you are having difficulties with streaming to Grbl, we will ask you to use this Python
streaming script to eliminate the GUI you are using as the source of the issue. Before posting to the
issues thread, please use this script to run your G-code program.
Included with the source code and officially supported by Grbl, two Python streaming scripts are supplied to
illustrate simple and more complex streaming methods that work well cross-platform. These scripts don't
fully support all of the Grbl's features, but are intended more as a way to compare or troubleshoot other
garden variety or newly-written GUIs out there. These are located in the 'script' folder on the main
repository. Note: The streaming scripts require the pySerial module installed.

Install the pySerial module.

Download simple_stream.py Python script.

Open the script in a plain text editor and change the following line to reflect your
system:

s = serial.Serial('/dev/tty.usbmodem1811',9600)

In place of /dev/tty.usbmodem1811(Mac), you should put the serial port device name
of your Arduino. This will be different for each machine and OS. For example, on a Linux
system this would look like /dev/ttyACM0. Or on a Windows machine, this may look
like COM3.

The script looks for and reads gcode from a file named grbl.gcode, you should create
this file and put the gcode you want to execute in it. Or simply change this name in the
script to your needs.

Open a terminal/command window and change directories to the location of the Python
script and execute the Python script with the following command:

./simple_stream.py

(Mac/Linux) python simple_stream.py (Windows)

You should now see the gcode being streamed to grbl along with 'ok' messages and
your machine should begin moving.

The other, more advanced streaming script stream.py has command line arguments and does not require
modifying the script itself, unlike simple_stream.py. The main difference is that stream.py uses a character
counting scheme to ensure that Grbl's serial read buffer is full, which effectively creates another buffer layer
on top of Grbl's internal motion queue. This allows for Grbl to access and parse the next G-code block
immediately from the serial read buffer, rather than wait for the 'ok' send and response in the
simple_stream.py script. This is very useful for motions, like curves, that have very rapid, short line

segments in succession that may cause buffer starvation, which can lead to strange motion hiccups. In other
words, it ensures a smoother motion. Use this script, if you are not afraid of command line or are
experiencing weird motions.

Other GUIs
grblUI

A simple graphical user interface: https://github.com/jgeisler0303/grblUI. Programmed in Java, using rxtx


for serial communication. Should theoretically run on Linux, Mac and Windows alike. Apparently some
problems on Mac. Any feedback, tips and tricks appreciated (Issues or Wiki in grblUI). Check out the ready
to use jar in the Downloads.
grblgui

A graphical G-Code Streamer: https://github.com/cody82/grblgui. Programmed in Java, using rxtx for serial
communication and OpenGL 2.0 for rendering.
Notable features:

It displays the job duration and remaining time to complete in minutes.

It displays current speed.

You can toggle feed hold and enter G-Code commands.

It displays the buffer status graphically on the toolpath!

In development:

Simulate the milling process and display the resulting model.

CNCinfusion [Windows]

Currently under development in C# https://github.com/nm156/CNCInfusion


Gcode Sender [Windows]

https://github.com/downloads/OttoHermansson/GcodeSender/gcodesender.exe
http://www.contraptor.org/forum/t-287260/gcode-sender-program

Serial Emulators:
Other than CoolTerm or PuTTY, Linux and Mac systems have a great lightweight serial emulator called
screen that's either built in or easily installable (apt-get install screen) through the terminal interface.
If your device is connected on /dev/ttyACM0 (for Mac, /dev/tty.usbxxxx), type screen /dev/ttyACM0
115200 to connect to the device at 115200 baud. There you'll be connected to Grbl. To exit
To get out of the screen interface, simply press Ctrl-a followed by a k.

Interfacing with Grbl


Sonny Jeon edited this page on Sep 2 2015 25 revisions

Grbl Interface
The interface for Grbl is fairly simple and straightforward. We have taken steps to try to make it as easy as
possible for new users to get started, and for GUI developers to write their own custom interfaces to Grbl.
Everything communicates through the serial interface on the Arduino USB port. You just need to connect
your Arduino to your computer with a USB cable. Use any standard serial terminal program to connect to
Grbl, such as: the Arduino IDE serial monitor, Coolterm, puTTY, etc. Or use one of the many great Grbl
GUIs out there in the Internet wild.
Just about every user interaction with Grbl is performed by sending it a string of characters, followed by an
enter. Grbl will then process the string, execute it accordingly, and then reply back with a response to tell
you how it went. These strings include sending Grbl: a G-code block to execute, commands to configure
Grbl's settings, to view how Grbl is doing, etc. At times, Grbl may not respond immediately. This happens
only when Grbl is busy doing something else, or waiting for some room to clear in its look-ahead planner
buffer so it can finish processing the previous line sent.
However, one exception to this are Grbl's real-time commands. These are picked directly from the incoming
serial stream to execute immediately and asynchronously. See our Configuring Grbl wiki to see what they
are and how they work.

Start Up Message
Grbl vX.Xx ['$' for help]

The start up message always prints upon startup, after a reset, or at program end. Whenever you see this
message, this also means that Grbl has completed re-initializing all systems, so everything starts out the
same every time you use Grbl.

vX.Xx indicates the major version number, followed by a minor version letter. The major

version number indicates the general release, while the letter simply indicates a feature
update or addition from the preceding minor version letter.

Grbl

Bug fix revisions are tracked by the build info number, printed when an $I command is
sent. These revisions don't update the version number and are given by date revised in
year, month, and day, like so 20140820.
$

Help Message

Every string Grbl receives is assumed to be a G-code block/line for it to execute, except for some special
system commands Grbl uses for configuration, provide feedback to the user on what and how it's doing, or
perform some task such as a homing cycle. To see a list of these system commands, type $ followed by an
enter, and Grbl will respond with:
$$ (view Grbl settings)
$# (view # parameters)
$G (view parser state)
$I (view build info)
$N (view startup blocks)
$x=value (save Grbl setting)
$Nx=line (save startup block)
$C (check gcode mode)
$X (kill alarm lock)
$H (run homing cycle)
~ (cycle start)
! (feed hold)
? (current status)
ctrl-x (reset Grbl)

Check out our Configuring Grbl wiki page to find out what all of these commands mean
and how to use them.

Grbl Response Meanings


Every G-code block sent to Grbl and Grbl system commands (excluding the real-time commands) will
respond with how it went. This section will describe Grbl's responses and their meanings.

ok: All is

good! Everything in the last line was understood by Grbl and was successfully processed
and executed.

error:Expected command letter:

error:Bad number format: The number

error:Invalid statement: The issued

error:Value < 0: The value

error:Setting disabled:

error:Value < 3 usec:

G-code is composed of G-code "words", which consists of a


letter followed by a number value. This error occurs when the letter prefix of a G-code word is
missing in the G-code block (aka line).
value suffix of a G-code word is missing in the G-code
block, or when configuring a $Nx=line or $x=val Grbl setting and the x is not a number value.
Grbl $ system command is not recognized or is invalid.

of a $x=val Grbl setting, F feed rate, N line number, P word, T tool


number, or S spindle speed is negative.
Homing is disabled when issuing a $H command.

Step pulse time length cannot be less than 3 microseconds (for technical

reasons).

error:EEPROM read fail. Using defaults:

If Grbl can't read data contained in the EEPROM,


this error is returned. Grbl will also clear and restore the effected data back to defaults.

error:Not idle:

error:Alarm lock:

error:Homing not enabled:

error:Line overflow:

Certain Grbl $ commands are blocked depending Grbl's current state, or what its
doing. In general, Grbl blocks any command that fetches from or writes to the EEPROM since the
AVR microcontroller will shutdown all of the interrupts for a few clock cycles when this happens.
There is no work around, other than blocking it. This ensures both the serial and step generator
interrupts are working smoothly throughout operation.
Grbl enters an ALARM state when Grbl doesn't know where it is and will then
block all G-code commands from being executed. This error occurs if G-code commands are sent
while in the alarm state. Grbl has two alarm scenarios: When homing is enabled, Grbl automatically
goes into an alarm state to remind the user to home before doing anything; When something has went
critically wrong, usually when Grbl can't guarantee positioning. This typically happens when
something causes Grbl to force an immediate stop while its moving from a hard limit being triggered
or a user commands an ill-timed reset.
Soft limits cannot be enabled if homing is not enabled, because Grbl
has no idea where it is when you startup your machine unless you perform a homing cycle.
Grbl has to do everything it does within 2KB of RAM. Not much at all. So,
we had to make some decisions on what's important. Grbl limits the number of characters in each
line to less than 80 characters (70 in v0.8, 50 in v0.7 or earlier), excluding spaces or comments. The
G-code standard mandates 256 characters, but Grbl simply doesn't have the RAM to spare. However,
we don't think there will be any problems with this with all of the expected G-code commands sent

to Grbl. This error almost always occurs when a user or CAM-generated G-code program sends
position values that are in double precision (i.e. -2.003928578394852), which is not realistic or
physically possible. Users and GUIs need to send Grbl floating point values in single precision (i.e.
-2.003929) to avoid this error.

ID

error:Modal group violation: The G-code parser

has detected two G-code commands that


belong to the same modal group in the block/line. Modal groups are sets of G-code commands that
mutually exclusive. For example, you can't issue both a G0 rapids and G2 arc in the same line, since
they both need to use the XYZ target position values in the line. LinuxCNC.org has some great
documentation on modal groups.

error:Unsupported command: The G-code parser

error:Undefined feed rate: There is

error:Invalid gcode ID:XX: To save some

doesn't recognize or support one of the G-code


commands in the line. Check your G-code program for any unsupported commands and either
remove them or update them to be compatible with Grbl.
no feed rate programmed, and a G-code command that
requires one is in the block/line. The G-code standard mandates F feed rates to be undefined upon a
reset or when switching from inverse time mode to units mode. Older Grbl versions had a default
feed rate setting, which was illegal and was removed in Grbl v0.9.
flash space, Grbl v0.9 installed some cryptic invalid
G-code numbers to indicate uncommon G-code programming errors. Storing full strings to describe
all of the errors would use up the rest of the precious flash space we have to work with. The most
common G-code errors, listed above, are still printed in human-readable strings though.
Description

23

A G or M command value in the block is not an integer. For example, G4 can't be G4.13.
Some G-code commands are floating point (G92.1), but these are ignored.

24

Two G-code commands that both require the use of the XYZ axis words were detected in the
block.

25 A G-code word was repeated in the block.


26

A G-code command implicitly or explicitly requires XYZ axis words in the block, but none
were detected.

The G-code protocol mandates N line numbers to be within the range of 1-99,999. We think
27 that's a bit silly and arbitrary. So, we increased the max number to 9,999,999. This error
occurs when you send a number more than this.
28

A G-code command was sent, but is missing some important P or L value words in the line.
Without them, the command can't be executed. Check your G-code.

29

Grbl supports six work coordinate systems G54-G59. This error happens when trying to use
or configure an unsupported work coordinate system, such as G59.1, G59.2, and G59.3.

30

The G53 G-code command requires either a G0 seek or G1 feed motion mode to be active. A
different motion was active.

31 There are unused axis words in the block and G80 motion mode cancel is active.
32

A G2 or G3 arc was commanded but there are no XYZ axis words in the selected plane to
trace the arc.

33 The motion command has an invalid target. G2, G3, and G38.2 generates this error. For both

ID

Description
probing and arcs traced with the radius definition, the current position cannot be the same
as the target. This also errors when the arc is mathematically impossible to trace, where
the current position, the target position, and the radius of the arc doesn't define a valid
arc.

A G2 or G3 arc, traced with the radius definition, had a mathematical error when computing
34 the arc geometry. Try either breaking up the arc into semi-circles or quadrants, or redefine
them with the arc offset definition.
35

A G2 or G3 arc, traced with the offset definition, is missing the IJK offset word in the
selected plane to trace the arc.

36 There are unused, leftover G-code words that aren't used by any command in the block.
37

The G43.1 dynamic tool length offset command cannot apply an offset to an axis other than
its configured axis. The Grbl default axis is the Z-axis.

Other Grbl Messages


Along with the normal responses from user input, Grbl provides additional messages for important feedback
of its current state. These messages are organized into three general classes: ALARM messages, feedback
messages, and real-time status messages.
Alarms

Alarm is an emergency state. Something has gone terribly wrong when these occur. Typically, they are
caused by limit error when the machine has moved or wants to move outside the machine space and crash
into something. They also report problems if Grbl is lost and can't guarantee positioning or a probe
command has failed. Once in alarm-mode, Grbl will lock out and shut down everything until the user issues
a reset. Even after a reset, Grbl will remain in alarm-mode, block all G-code from being executed, but allows
the user to override the alarm manually. This is to ensure the user knows and acknowledges the problem and
has taken steps to fix or account for it.
All alarm messages start with ALARM:`, followed by a brief description of the alarm cause.

ALARM:Hard/soft limit:

Hard and/or soft limits must be enabled for this error to occur. With hard
limits, Grbl will enter alarm mode when a hard limit switch has been triggered and force kills all
motion. Machine position will be lost and require re-homing. With soft limits, the alarm occurs when
Grbl detects a programmed motion trying to move outside of the machine space, set by homing and
the max travel settings. However, upon the alarm, a soft limit violation will instruct a feed hold and
wait until the machine has stopped before issuing the alarm. Soft limits do not lose machine position
because of this.

ALARM:Abort during cycle: This

ALARM:Probe fail: The G38.2

alarm occurs when a user issues a soft-reset while the machine is


in a cycle and moving. The soft-reset will kill all current motion, and, much like the hard limit alarm,
the uncontrolled stop causes Grbl to lose position.
straight probe command requires an alarm or error when the probe
fails to trigger within the programmed probe distance. Grbl enters the alarm state to indicate to the
user the probe has failed, but will not lose machine position, since the probe motion comes to a
controlled stop before the error.

Feedback Messages

Feedback messages provide non-critical information on what Grbl is doing and/or what it needs. Not too
complicated. Feedback message are always enclosed in [] brackets.

[Reset to continue]:

Sent after an alarm message to tell the user to reset Grbl as an


acknowledgement that an alarm has happened.

['$H'|'$X' to unlock]: After

[Caution: Unlocked]: The alarm mode

[Enabled]: A simple

an alarm and the user has sent a reset, this feedback message is sent
after the startup message to tell the user that all G-code commands are locked out, until the user
unlocks it manually with the $X command or performs a homing cycle. Also, if a user has homing
enabled, this message also is sent upon a fresh power-up to indicate the user needs to home the
machine before doing anything else.
can be manually over-ridden by the user issuing a $X
command. This feedback message is sent when the user overrides the alarm.
feedback message to indicate to the user that a Grbl state or mode has been

enabled.

[Disabled]:

Same as above, but notifies state or mode has been disabled.

Other Messages:

[PRB:0.000,0.000,1.492:1]: This

is a little out of place, but as a service to GUIs, Grbl will


immediately send a feedback message containing the triggered probe position upon a successful
G38.2 straight probe command. This data can also be viewed in the parameters print out called by
$#.
o

[G0 G54 G17 G21 G90 G94 M0 M5 M9 T0 F0. S0.]: When

a $G system command is sent, Grbl


replies with a message containing the current G-code parser modal state.
o

(Grbl v0.9i or later) The :1 suffix value is a boolean that denotes whether the last
probe cycle was successful or not.

(Grbl 0.9i and later) S0. denotes spindle speed and prints only if variable spindle
speed is enabled.

$# View Parameters: When

a $# system command is sent, Grbl replies with several messages


containing the current G-code parameter, which includes the work coordinate offsets, pre-defined
positions, G92 coordinate offset, tool length offset, and last probe position. All of this data is printed
with the feedback message [] brackets.

Writing an Interface for Grbl


FOR DEVELOPERS ONLY: This section outlines the recommended ways to setup a communications
and streaming protocol with Grbl for a GUI.
The general interface for Grbl has been described above, but what's missing is how to run an entire G-code
program on Grbl, when it doesn't seem to have an upload feature. Or, how to build a decent GUI with realtime feedback. This is where this section fits in. Early on, users fiercely requested for flash drive, external
RAM, LCD support, joysticks, or network support so they can upload a g-code program and run it directly

on Grbl. The general answer to that is, good ideas, but Grbl doesn't need them. Grbl already has nearly all of
the tools and features to reliably communicate with a simple graphical user interface (GUI). Plus, we want to
minimize as much as we can on what Grbl should be doing, because, in the end, Grbl needs to be
concentrating on producing clean, reliable motion. That's it.

Streaming a G-Code Program to Grbl


Here we will describe three different streaming methods for Grbl GUIs, but really there's only two that we
recommend using. One of the main problems with streaming to Grbl is the USB port itself. Arduinos and
most all micro controllers use a USB-to-serial converter chip that, at times, behaves strangely and not
typically how you'd expect, like USB packet buffering and delays that can wreak havoc to a streaming
protocol. Another problem is how to deal with some of the latency and oddities of the PCs themselves,
because none of them are truly real-time and always create micro-delays when executing other tasks.
Regardless, we've come up with ways to ensure the G-code stream is reliable and simple.
Streaming Protocol: Simple Send-Response [Recommended for Grbl v0.9+]

The send-response streaming protocol is the most fool-proof and simplest method to stream a G-code
program to Grbl. The host PC interface simply sends a line of G-code to Grbl and waits for an ok or error:
response before sending the next line of G-code. So, no matter if Grbl needs to wait for room in the lookahead planner buffer to finish parsing and executing the last line of G-code or if the the host computer is
busy doing something, this guarantees both to the host PC and Grbl, the programmed G-code has been sent
and received properly. An example of this protocol is published in our simple_stream.py script in our
repository.
However, it's also the slowest of three outlined streaming protocols. Grbl essentially has two buffers
between the execution of steps and the host PC interface. One of them is the serial receive buffer. This
briefly stores up to 127 characters of data received from the host PC until Grbl has time to fetch and parse
the line of G-code. The other buffer is the look-ahead planner buffer. This buffer stores up to 17 line motions
that are acceleration-planned and optimized for step execution. Since the send-response protocol receives a
line of G-code while the host PC waits for a response, Grbl's serial receive buffer is usually empty and
under-utilized. If Grbl is actively running and executing steps, Grbl will immediately begin to execute and
empty the look-ahead planner buffer, while it sends the response to the host PC, waits for the next line from
the host PC, upon receiving it, parse and plan it, and add it to the end of the look-ahead buffer.
Although this communication lag may take only a fraction of a second, there is a cumulative effect, because
there is a lag with every G-code block sent to Grbl. In certain scenarios, like a G-code program containing
lots of sequential, very short, line segments with high feed rates, the cumulative lag can be large enough to
empty and starve the look-ahead planner buffer within this time. This could lead to start-stop motion when
the streaming can't keep up with G-code program execution. Also, since Grbl can only plan and optimize
what's in the look-ahead planner buffer, the performance through these types of motions will never be fullspeed, because look-ahead buffer will always be partially full when using this streaming method. If your
expected application doesn't contain a lot of these short line segments with high feed rates, this streaming
protocol should be more than adequate for a vast majority of applications, is very robust, and is a quick way
to get started. However, we do not recommend using this method for Grbl versions v0.8 or prior due to some
performance issues with these versions.
Streaming Protocol: Via Flow Control (XON/XOFF)

To avoid the risk of starving the look-ahead planner buffer, a flow control streaming protocol can be used to
try to keep Grbl's serial receive buffer full, so that Grbl has immediate access to the next g-code line to parse
and plan without having to wait for the host PC to send it. Flow control, also known as XON/XOFF
software flow control, uses two special characters to tell the host PC when it has or doesn't have room in the
serial receive buffer to receive more data. When there is room, usually at 20% full, the special character is
sent to the host PC indicating ready-to-receive. The host PC will begin to send data until it receives the other

stop-receive special character, usually at 80% full. Grbl's XON/XOFF software flow control feature may be
enabled through the config.h, but is not officially supported for the following reasons.
While sound in logic, software flow control has a number of problems. The timing between Grbl and the
host PC is almost never perfectly in sync, in large part due to the USB protocol and the USB-serial converter
chips on every Arduino. This poses a big problem when sending and receiving these special flow-control
characters. When Grbl's serial receive buffer is low, the time between when it sends the ready-to-receive
character and when the host PC sends more data all depends everything in between. If the host PC is busy or
the Arduino USB-serial converter is not sending the character on time, this lag can cause Grbl to wait for
more serial data to come in before parsing and executing the next line of G-code. Even worse though, if the
serial receive buffer is nearing full and the stop-receive character is sent, the host PC may not receive the
signal in time to stop the data transfer and over-flow Grbl's serial buffer. This is bad and will corrupt the data
stream.
Because the software flow-control method is dependent on the performance of the USB-serial converter on
the Arduino and the host PC, the low and high watermarks for the ready-to-receive and stop-receive
characters must be tuned for each case. Thus, it's not really a robust solution. In our experience with
XON/XOFF software flow control, it absolutely DOES NOT work with Arduinos with the Atmega8U/16U
USB-serial converter chips (on all current Arduinos from the Uno to Mega2560). For some reason, there are
USB packet delays that are out of Grbl's control and almost always led to data corruption. However,
XON/XOFF worked, but only on older Arduinos or micro controllers that featured an FTDI RS232 USBserial converter chip, such as the Duemilanove or controllers with an FTDI break-out board. The FTDI's
firmware reliably sent the XON/XOFF special characters in time and on time. We're not sure why there is
such a difference between them.
If you decide to use XON/XOFF software flow control for your GUI, keep in mind that, at the moment, it'll
only really works with FTDI USB-serial converters. But, the great thing about this method is that you can
connect with Grbl over a serial emulator program like Coolterm, enable XON/XOFF flow control, cut-andpaste an entire g-code program into it, and Grbl will execute it completely. (Nice but not really necessary.)
Streaming Protocol: Character-Counting [Recommended with Reservations]

To get the best of both worlds, the simplicity and reliability of the send-response method and assurance of
maximum performance with software flow control, we came up with a simple character-counting protocol
for streaming a G-code program to Grbl. It works like the send-response method, where the host PC sends a
line of G-code for Grbl to execute and waits for a response, but, rather than needing special XON/XOFF
characters for flow control, this protocol simply uses Grbl's responses as a way to reliably track how much
room there is in Grbl's serial receive buffer. An example of this protocol is outlined in the stream.py
streaming script in our repo.
The main difference between this protocol and the others is the host PC needs to maintain a standing count
of how many characters it has sent to Grbl and then subtract the number of characters corresponding to the
line executed with each Grbl response. Suppose there is a short G-code program that has 5 lines with 25, 40,
31, 58, and 20 characters (counting the line feed and carriage return characters too). We know Grbl has a 127
character serial receive buffer, and the host PC can send up to 127 characters without overflowing the buffer.
If we let the host PC send as many complete lines as we can without over flowing Grbl's serial receive
buffer, the first three lines of 25, 40, and 31 characters can be sent for a total of 96 characters. When Grbl
responds, we know the first line has been processed and is no longer in the serial read buffer. As it stands,
the serial read buffer now has the 40 and 31 character lines in it for a total of 71 characters. The host PC
needs to then determine if it's safe to send the next line without overflowing the buffer. With the next line at
58 characters and the serial buffer at 71 for a total of 129 characters, the host PC will need to wait until more
room has cleared from the serial buffer. When the next Grbl response comes in, the second line has been

processed and only the third 31 character line remains in the serial buffer. At this point, it's safe to send the
remaining last two 58 and 20 character lines of the g-code program for a total of 109.
While seemingly complicated, this character-counting streaming protocol is extremely effective in practice.
It always ensures Grbl's serial read buffer is filled, while never overflowing it. It maximizes Grbl's
performance by keeping the look-ahead planner buffer full by better utilizing the bi-directional data flow of
the serial port, and it's fairly simple to implement as our stream.py script illustrates. We have stress-tested
this character-counting protocol to extremes and it has not yet failed. Seemingly, only the speed of the serial
connection is the limit.
UPDATE: Up until recently, we've recommended that Grbl GUIs use this streaming protocol. It is indeed
very efficient and effective, but there are a couple of additional things interface writers should aware of.
These are issues being worked on for the v1.0 release.

Since the GUI is preloading Grbl's serial RX buffer with commands, Grbl will continually
execute all of the queued g-code in the RX serial buffer. The first problem is if there is
an error at the beginning of the RX buffer, Grbl will continue to execute the remaining
buffered g-code and the GUI won't be able to control what happens. The interim
solution is to check all of the g-code via the $C check mode, so all errors are vetted
prior to streaming.

When Grbl stores data to EEPROM, the AVR requires all interrupts to be disabled during
this write process, including the serial RX ISR. This means that if a g-code or Grbl $
command writes to EEPROM, the data sent during the write may be lost. This is usually
rare and typically occurs when streaming a G10 command inappropriately inside a
program. For robustness, GUIs should track and detect these EEPROM write commands
and handle them appropriately by waiting for the queue to finish executing before
sending more data. Note that the simple send-response protocol doesn't not suffer
from this issue.

Interacting with Grbl's Systems


Along with streaming a G-code program, there a few more things to consider when writing a GUI for Grbl,
such as how to use status reporting, real-time control commands, dealing with EEPROM, and general
message handling.
Status Reporting

When a ? character is sent to Grbl (no additional line feed or carriage return character required), it will
immediately respond with something like <Idle,MPos:0.000,0.000,0.000,WPos:0.000,0.000,0.000>
to report its state and current position. The ? is always picked-off and removed from the serial receive buffer
whenever Grbl detects one. So, these can be sent at any time. Also, to make it a little easier for GUIs to pick
up on status reports, they are always encased by <> chevrons.
Developers can use this data to provide an on-screen position digital-read-out (DRO) for the user and/or to
show the user a 3D position in a virtual workspace. We recommend querying Grbl for a ? real-time status
report at no more than 5Hz. 10Hz may be possible, but at some point, there are diminishing returns and you
are taxing Grbl's CPU more by asking it to generate and send a lot of position data.
Grbl's status report is fairly simply in organization. It always starts with a word describing the machine state
like IDLE (descriptions of these are available elsewhere in the Wiki). The following data values are usually
in the order listed below and separated by commas, but may not be in the exact order or printed at all. Report
output depends on the user's $10 status report mask setting.

MPos:0.000,0.000,0.000 : Machine position listed as X,Y,Z coordinates. Units (mm or


inch) depends on $13 Grbl unit reporting setting.

WPos:0.000,0.000,0.000 : Work position listed as X,Y,Z coordinates. Units (mm or inch)


depends on $13 Grbl unit reporting setting.

Buf:0 : Number of motions queued in Grbl's planner buffer.

RX:0 : Number of characters queued in Grbl's serial RX receive buffer.

Real-Time Control Commands

The real-time control commands, ~ cycle start/resume, ! feed hold, and ^X soft-reset, all immediately signal
Grbl to change its running state. Just like ? status reports, these control characters are picked-off and
removed from the serial buffer when they are detected and do not require an additional line-feed or carriagereturn character to operate.
EEPROM Issues

EEPROM access on the Arduino AVR CPUs turns off all of the interrupts while the CPU reads and writes to
EEPROM. This poses a problem for certain features in Grbl, particularly if a user is streaming and running a
g-code program, since it can pause the main step generator interrupt from executing on time. Most of the
EEPROM access is restricted by Grbl when it's in certain states, but there are some things that developers
need to know.

Settings can't be streamed to Grbl with either the XON/XOFF software flow control or the charactercounting streaming protocols. Only the simple send-response protocol works. This is because during
the EEPROM write, the AVR CPU also shuts-down the serial RX interrupt, which means data can
get corrupted or lost. Note that the send-response protocol doesn't send any data until a response
comes back.

When changing work coordinates, printing $# parameters, or accessing the G28/G30 predefined
positions, Grbl has to fetch them from EEPROM. There is a small chance this access can pause the
stepper or serial receive interrupt long enough to cause motion issues, but since it only fetches 12
bytes at a time at 2 cycles per fetch, the chances are very small that this will do anything to how Grbl
runs. We just suggest keeping an eye on this and report to us any issues you might think are related to
this.

For reference:

Grbl's EEPROM write commands: G10 L2, G10 L20, G28.1, G30.1, $x=, $I=, $Nx=, $RST=

Grbl's EEPROM read commands: G54-G59, G28, G30, $$, $I, $N, $#

Message Handling

Most of the feedback from Grbl fits into nice categories so GUIs can easily tell what is what. Here's how
they are organized:

ok: Standard all-is-good response to a single line sent to Grbl.

error:: Standard error response to a single line sent to Grbl.

ALARM:: A critical error message that occurred. All processes stopped until user

acknowledgment.

[]: All feedback messages are sent in brackets. These include parameter and g-code

parser state print-outs.

<>: Status reports are sent in chevrons.

There are few things that don't fit neatly into this setup at the moment. In the next version, we'll try to make
this more universal, but for now, your GUIs will need to manually account for these:

The startup message.

$ Help print-out.

$N Start-up blocks execution after the startup message.

The $$ view Grbl settings print-out.

G-code Error Handling

As of Grbl v0.9, the g-code parser is fully standards-compilant with complete error-checking. When a Gcode parser detects an error in a G-code block/line, the parser will dump everything in the block from
memory and report an error: back to the user or GUI. This dump can pose problematic, because the bad Gcode block may have contained some valuable positioning commands or feed rate settings.
It's highly recommended to do what all professional CNC controllers do when they detect an error in the Gcode program, halt. Don't do anything further until the user has modified the G-code and fixed the error in
their program. Otherwise, bad things could happen.
As a service to GUIs, Grbl has a "check G-code" mode, enabled by the $C system command. GUIs can
stream a G-code program to Grbl, where it will parse it, error-check it, and report ok's and errors:'s
without powering on anything or moving. So GUIs can pre-check the programs before streaming them for
real. To disable the "check G-code" mode, send another $C system command and Grbl will automatically
soft-reset to flush and re-initialize the G-code parser and the rest of the system. This perhaps should be run
in the background when a user first loads a program, before a user sets up his machine. This flushing and reinitialization clears G92's by G-code standard, which some users still incorrectly use to set their part zero.
Jogging

Unfortunately, Grbl doesn't have a proper jogging interface, at least for now. This was to conserve precious
flash space for the development of Grbl v0.9, but may be installed in the next release of Grbl. However,
authors of Grbl GUIs have come up with ways to simulate jogging with Grbl by sending incremental
motions, such as G91 X0.1, with each jogging click or key press. This works pretty well, but, if
uncontrolled, a user can easily queue up more motions than they want without realizing it and move wellpast their desired location.
The general methodology that has been shown to work is to simply restrict the number of jogging
commands sent to Grbl. This can be done by disabling key repeating when held down. The planner buffer
queue size can be tracked such that only a handful of motions can be queued and executed.
Synchronization

For situations when a GUI needs to run a special set of commands for tool changes, auto-leveling, etc, there
often needs to be a way to know when Grbl has completed a task and the planner buffer is empty. The
absolute simplest way to do this is to insert a G4 P0.01 dwell command, where P is in seconds and must be
greater than 0.0. This acts as a quick force-synchronization and ensures the planner buffer is completely
empty before the GUI sends the next task to execute.

G Code Examples
William Adams edited this page on Mar 16 2015 3 revisions

This wiki page is intended to provide example G-code programs to test and proof Grbl. Please feel free to
contribute short programs with detailed descriptions of their movements and purpose. As a rule of thumb,

keep these example programs short, easy to edit, and generic for testing on a variety of machines with travel
and feedrate limits in mind.

Tips

It's always good practice to insert a comment header at the beginning of your program
to remind you of what your program does, if it's been proven to work, when you wrote
it, what tool it's been written for, what size stock you'll need, and where the part origin
(beginning point) is located. Most of the time, good CAM programs will automatically do
this for you, but if yours doesn't, here's an example.

(DIAMOND, CIR, SQ TEST PROGRAM)


(FEB-08-12, 12:05)
( *** UNPROVEN PROGRAM *** )
( RUN IN VISE ON PARALLELS )
(Z OFFSET: TOP OF MATERIAL WITH )
( 0.375" MATERIAL ABOVE VISE JAWS )
(X0,Y0,Z0= Center, Center, Top)
(STOCK ORIGIN = X0. Y0. Z.01)
(MATERIAL TYPE= ALUMINUM inch - 6061)
(MATERIAL SIZE= X1.75 Y1.75 Z.5)
(TOOL= 1/4 2-FLUTE HSS END MILL)

Place an initialization block at the beginning of your program to set all of the G-code
modes explicitly for your program. These are things such as mm/inch modes,
incremental/absolute modes, feedrate modes, plane selection, or work coordinate
system. Even though the defaults of your machine may work with your G-code program
now, this doesn't mean that it will later or if you forget it was set differently by a
previous program. This can result in a crash. An initialization block typically looks
something like this.

G17 G20 G90 G94 G54

Examples
Draw a Circle

This program draws a 1" diameter circle about the origin in the X-Y plane. It should begin by seeking the Zaxis to 0.25", travel to X=-0.5 and Y=0.0, and lower back to Z=0.0. The program will then draw a clockwise
circle at a slow feedrate. When finished, it will lift the Z-axis up 0.1" and then seek back to X=0.0, Y=0.0,
and Z=0.25 to complete.
G17 G20 G90 G94 G54
G0 Z0.25
X-0.5 Y0.
Z0.1
G01 Z0. F5.
G02 X0. Y0.5 I0.5 J0. F2.5
X0.5 Y0. I0. J-0.5
X0. Y-0.5 I-0.5 J0.
X-0.5 Y0. I0. J0.5
G01 Z0.1 F5.
G00 X0. Y0. Z0.25

Known Bugs
109JB edited this page on Apr 5 16 revisions

This wiki is intended to provide information on known bugs. Please feel free to contribute more known bugs
and their work arounds as they are discovered. When a bug is fixed, they will be removed from this list.

Character-counting Streaming Protocol Issues

While the character-counting streaming protocol is indeed very efficient and effective, there are a
couple of newly uncovered issues interface writers should aware of. These are issues being worked
on for the v1.0 release.
o Since the GUI is preloading Grbl's serial RX buffer with commands, Grbl will continually
execute all of the queued g-code in the RX serial buffer. The first problem is if there is an
error at the beginning of the RX buffer, Grbl will continue to execute the remaining buffered
g-code and the GUI won't be able to control what happens. The interim solution is to check
all of the g-code via the $C check mode, so all errors are vetted prior to streaming.
o When Grbl stores data to EEPROM, the AVR requires all interrupts to be disabled during this
write process, including the serial RX ISR. This means that if a g-code or Grbl $ command
writes to EEPROM, the data sent during the write may be lost. This is usually rare and
typically occurs when streaming a G10 command inappropriately inside a program. For
robustness, GUIs should track and detect these EEPROM write commands and handle them
appropriately by waiting for the queue to finish executing before sending more data. Note
that the simple send-response protocol doesn't not suffer from this issue.

USB to Serial transmission errors

It has been found that both genuine Arduino boards, and clone Arduino boards experience occasional
errors in transmission of data from the host computer to Grbl. The related errors could result in
unwanted motion of the machine. The problem was originally discovered on a an Arduino clone that
used a CH340G USB to serial chip, but the problem is also present to a lesser degree on genuine
Arduino's and clones that use the Atmel 16U2 chip. There is no fix for the CH340G USB to serial
chip. An updated firmware is required to eliminate the problem on the boards using the 16U2 chip.

Clone Arduino boards using the CH340G USB to Serial chip experience occasional transmission
errors and their use is at your own risk. There is no current fix for this problem on CH340G equipped
boards.

Genuine Arduino boards and clone Arduino boards using the Atmel 16U2 USB to Serial chip also
experience occasional transmission errors and it is recommended that users re-flash the 16U2 chip
with updated firmware. You can use the instructions here:
https://www.arduino.cc/en/Hacking/DFUProgramming8U2 to falsh the new firmware, and the new
firmware can be found
here:https://github.com/AlexHolden/Arduino/tree/master/hardware/arduino/avr/firmwares/atmegaxx
u2/arduino-usbserial Many thanks to user AlexHolden for taking the time to edit the firmware to
solve this problem.

You can read more about the problem in the issue here: https://github.com/grbl/grbl/issues/845

You might also like