From ShapeOko
Jump to navigation Jump to search

Note that the main documentation for Grbl is: for 1.0 or later

This page is intended as a convenient reference for Shapeoko users, but has grown somewhat organically, containing those things which have been specifically brought up on the forums or added in here. In any case of doubt please consult the Grbl documentation.


(from Grbl is a free, open source, high performance software for controlling the motion of machines that make things and will run on a straight Arduino. If the maker movement was an industry, Grbl would be the industry standard.

Most MakerBots and 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.

Grbl is a no-compromise, high performance, low cost alternative to parallel-port-based motion control for CNC milling. It will run on a vanilla Arduino (Duemillanove/Uno) as long as it sports an Atmega 328[1]. The controller is written in highly optimized C utilizing every clever feature of the AVR-chips to achieve precise timing and asynchronous operation. It is able to maintain more than 30kHz of stable, jitter free control pulses.

It accepts standards-compliant G-code and has been tested with the output of several CAM tools with no problems. Arcs, circles and helical motion are fully supported – but no support for functions or variables as these are apocryphal and fell into disuse after humans left G-code authoring to machines some time in the 80s.

Grbl includes full acceleration management with look ahead. That means the controller will look up to 18 motions into the future and plan its velocities ahead to deliver smooth acceleration and jerk-free cornering.

In 2009, Simen Svale Skogsrud ( graced the open-source community by writing and releasing the early versions of Grbl to everyone. Since 2011, Grbl is pushing ahead as a community-driven open-source project under the pragmatic leadership of Sonny Jeon Ph.D. (@chamnit).

The project was initially inspired by the Arduino GCode Interpreter by Mike Ellery

Discussion of settings here:


Note that it is possible to corrupt the bootloader if something goes wrong when flashing. If that occurs, one either needs an AVI ISP programmer (a specialized piece of equipment) or a second Arduino which may be configured to function as an ISP programmer: [2]

Github instructions here:

There are two different files to download.

  1. Hex file - The code that'll run on the Arduino. Download from github repository here
  2. XLoader - A program that will upload the hex file to your Arduino.

If your computer has never used an Arduino before you may also need to install the Arduino com port drivers. The drivers are in the Arduino Environment package. Follow your OS Getting Started Guide at You only need to follow the guide up to the point where the drivers get installed.

  • Here are 2 pre-compiled Hex Files if you're using the v1 stepper shield from
    • Version 0.7D here.
    • Version 0.8E here (save as grbl8.hex)

General Hex Files:

Grbl 0.9j

This is the newest version, linked to from the Grbl main page:

Instructions on upgrading:

Grbl 0.9g (Shapeoko 3)

There is a copy of Grbl w/ defaults for the Nomad883 at: --- the settings should be adjusted to match: and the micro-stepping settings on your control board.

Note that on newer versions of the Carbide Motion Machine Control Board there is a button which must be pressed to allow the board to be flashed.[3]

Shapeoko 2 Hex File[4]


Grbl v0.9i Atmega328p 16mhz 115200baud with ShapeOko2 defaults (2015-03-29)


Note that it may be necessary to clear any coordinate offsets or other persistent settings when upgrading.[5]

  1. Make a copy of your current settings. I simply took a photo of my screen showing the settings ($$).
  2. Made certain I knew which port my SO was running on.
  3. Downloaded the hex file from github for the SO2, I am presuming you have a stock setup.
  4. Download a program for flashing (Windows: XLoader, Mac OS X: HexUploader, Linux: Easy Flash script) also from github and extract the file.
  5. Started running the Loader program. Input your , processor (Arduino Uno), comm port and the destination of where you put the saved hex file for the SO2 and hit start. Should start and be finished in few seconds with a message 28030 bits transferred.
  6. Close the Loader program and open your grbl controller and connect at 115200 baud and NOT 9600. You should see that is has 0.9g 0.9i loaded.
  7. Ensure your axes are still working correctly. 2 of my axes were suddenly reversed. Update $3 using settings from grbl's wiki for configuring them.
  8. Check that your settings have not changed by using your photo from step 1. If you used the stock SO2 hex file the only issues I had were my inverted axes.

A further consideration “The spindle enable pin D12 and z-limit pin D11 have switched places in v0.9i.”[6]

Shapeoko 3:



Clearing settings

To clear:[8]

  • WCS: clear with G10 L2 P1 X0 Y0 Z0, then repeat with P2, ..., P6. Note that's L2, not L20.
  • Startup lines: clear with $N0= and $N1= (nothing after the equal sign).
  • Settings: just enter new settings instead (e.g. $1=255).

Wiring Diagram

A basic one for the stepper motors is shown as part of the assembly instructions:

Wiring diagram for ShapeOko 2 --- grbl 0.9 includes: probe, relay wiring, limit switch wiring and Arduino USB to PC on-board USB wiring.

Commands for Grbl

Note that these may be included in G-code files intended to only be sent to a machine running Grbl

! pause [9]

~ resume cycle

Editing for Stepper Shield

Using the stepper shield requires modifications to the pin assignments prior to compiling grbl. Make these edits to the source (this is taken from around Grbl 0.8, posted by Edward on the mailing list):


#define STEPPERS_DISABLE_BIT         0

#define STEPPERS_ENABLE_VAL     0  // 0=low 1=high

#define STEPPING_DDR       DDRD
#define X_STEP_BIT           2
#define Y_STEP_BIT           4
#define Z_STEP_BIT           6
#define X_DIRECTION_BIT      3
#define Y_DIRECTION_BIT      5
#define Z_DIRECTION_BIT      7

#define LIMIT_DDR      DDRB
#define LIMIT_PIN     PINB
#define X_LIMIT_BIT          1
#define Y_LIMIT_BIT          4
#define Z_LIMIT_BIT          5



Stepper.c (insert this text on line 276):

// set enable pin
    STEPPERS_ENABLE_DDR &= 1<<STEPPERS_ENABLE_BIT;  // bit low is enable
    STEPPERS_ENABLE_PORT |= 1<<STEPPERS_ENABLE_BIT; // bit high is enable

Config for Grbl 0.7d (the stable branch)

I don't know why but the config.h I (DrRob) have used for 0.7d is quite different to the above:

#define STEPPERS_DISABLE_BIT         0

#define STEPPING_DDR       DDRD
#define X_STEP_BIT           2
#define Y_STEP_BIT           4
#define Z_STEP_BIT           6
#define X_DIRECTION_BIT      3
#define Y_DIRECTION_BIT      5
#define Z_DIRECTION_BIT      7

#define LIMIT_DDR      DDRB
#define LIMIT_PIN     PINB
#define X_LIMIT_BIT          1
#define Y_LIMIT_BIT          2
#define Z_LIMIT_BIT          3



and no changes to any C files. I'm using this with my Stripboard stepper driver carrier board, which has the same pin assignments as the Buildlog Stepper Shield.

Here is the hex file: Drrob-grbl-0.7.txt‎ (download and change the file extension to ".hex")

Notes on using Grbl with Synthetos Grblshield

There are no changes required to the github distributed versions of grbl operate a Synthetos grblshield.
Grblshield is compatible with grbl version 0.7x and later releases. As of March 3, 2013 the current grbl production release is 0.8c

Note about the Z axis microstep modification Shapeoko can run faster and more optimally if the microstep setting for Z is changed independently of X and Y. This is because X and Y are belt driven and Z is screw driven. You can set the microsteps on the v4 grblshields (blue boards) with a jumper. For earlier boards (green boards) a simple board modification can be made to leave X and Y at their default 8x microstep values while changing Z to 2x microstepping. This mod can be requested when you purchase a grblshield, and is included in all the Inventables full-kit purchases. If you have an earlier board or are just curious, full details of the process are shown here.

Installation and configuration

Notes on installing Grbl on a MEGA2560 in the forums: GRBL on Mega2560 - Solution.


Flashing a hex file to your arduino is simple with windows.


(For information on how to compile grbl from scratch on windows, see this page)

  • Download and extract xloader.
  • Open Xloader
  • Select the hex file
  • Select your Arduino Device type (for example: Uno(ATmega328)
  • Select the COM port from the drop down menu on the lower left
    • To Determine your arduino's COM port:
      • Windows XP: Right click on "My Computer", select "properties", select "device manager".
      • Windows 7: 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.
    • If you do not have a com port entry for your Arduino look for the exclamation point in the yellow triangle that signals a "unknown device". You will need to install the Arduino drivers. Follow the Arduino link above and install the drivers (unzip the dev package, right click on "unknown device", tell it update driver, surf to the drivers directory in the arduino dev package.
    • * If there are multiple USB serial ports, right click each one and check the manufacturer, the arduino will be FTDI. (Mine is Com6)
  • After your COM port has been determined, double check the baud rate (you shouldn't have the change it). Duemilanove/Nano (ATmega328): 57600, Uno (ATmega 328): 115200.
  • 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.


  • Linux use avrdude (Tested on Arduino Duemlianove and Arduino UNO)
    • Download latest release from and extract files on Desktop.
    • Download one of the prebuilt .hex-files from the Github downloads-page.
    • Locate avrdude inside the Arduino IDE folder. It will be something like this:
  /home/[user name]/Desktop/arduino-1.0/hardware/tools/avrdude
    • Connect the arduino to you computer.
    • Discover the name of the Arduino serial port. Duemilanove boards appear like ttyUSBX where X is a number. Uno boards appear like ttyACMX where X is a number. You can use the command:
  ls /dev/tty*
    • In case you have more than one ttyUSBX or ttyACMX, unplug the board, run the command again, and compare the two lists.
    • For versions previous to Arduino 1.0 go to the avrdude location and run this command:
  ./avrdude -C avrdude.conf -pm328p -cstk500 -P/dev/[port name] -D -Uflash:w:[hex-file location and name].hex
    • For Arduino 1.0 the command is:
  ./avrdude -C avrdude.conf -pm328p -carduino -P/dev/[port name] -D -Uflash:w:[hex-file location and name].hex
  • Note: some bootloaders (eg Arduino Pro) use 57600 baud rate. If you get "programmer is not responding" or "not in sync", try adding "-b 57600" to the avrdude command line
    • You should see something like this:
  avrdude: AVR device initialized and ready to accept instructions
  Reading | ################################################## | 100% 0.01s
  avrdude: Device signature = 0×1e9406
  avrdude: erasing chip
  avrdude: reading input file “grbl.hex”
  avrdude: input file grbl.hex auto detected as Intel Hex
  avrdude: writing flash (14228 bytes):
  Writing | ################################################## | 100% 8.06s
  avrdude: 14228 bytes of flash written
  avrdude: verifying flash memory against grbl.hex:
  avrdude: load data flash data from input file grbl.hex:
  avrdude: input file grbl.hex auto detected as Intel Hex
  avrdude: input file grbl.hex contains 14228 bytes
  avrdude: reading on-chip flash data:
  Reading | ################################################## | 100% 6.45s
  avrdude: verifying …
  avrdude: 14228 bytes of flash verified
  avrdude: safemode: Fuses OK
  avrdude done. Thank you.


Configuring Grbl

The ShapeOko Grbl calculator can help you to choose the settings for Grbl. See also Calculating Z-axis for an in-depth explanation.

Use a serial terminal to connect to grbl (to-do: how to determine which serial/usb device to connect the terminal to). The default connection parameters are: 9600 baud, 8 bits, no parity, 1 stop bit. (Windows 7 users will need a terminal program. PuTTY is a good, free option. Select "serial" for the Connection Type and set the baud to 9600). After connecting, you can type $ and press Enter to see the current configuration.

The folks over at the grbl github repository recommend that "the step sizes should be just under the precision of the machine, which is usually around 0.01mm for just about any machine, even production CNCs." In other words, around 100 steps/mm. They also explained that increasing the number of microsteps decreases torque and maximum speed, so we want to keep this number to a minimum if we can do so without excessively reducing the resolution.

The Z axis moves with 320 steps/mm with no microstepping, so it doesn't seem necessary to use microstepping on that axis. With 400 steps/rev motors, we get closest to 100 steps/mm with 8x microstepping.

Therefore, the following grbl configuration is suitable for:

  • 400 steps/rev stepper motors
  • 8 microsteps per step for X and Y
  • Full stepping for Z

You can copy and paste the above into the serial terminal to change the settings, which are stored into EEPROM immediately. Type $ and press Enter and check that the settings have been saved correctly.

You may find the Z axis to be a bit noisy at slow speeds in full-step mode. If so, switch to 1/4 step mode (jumper on MS2), and change:


$3 is reduced a bit because the pulse period is ~42us at max speed.

Soft Limits

You may want to configure these, even (or especially?) you have limit switches. Note that Carbide 3D recommends against enabling them in Carbide Motion.

Do some experimenting to determine the actual limits of travel in X and Y until just before the limit switches are triggered. Then set the GRBL "soft limit" settings appropriately, e.g.,[10]

$130=415.000 (x max travel, mm)
$131=430.000 (y max travel, mm)

840mm works well for a Shapeoko XXL.[11]

Invert Bits


$3 for Grbl 0.9, default for Shapeoko 3:

   $3=6 (dir port invert mask:00000110)

X axis is 1, Y is 2, and Z is 4.[12]

Value   Mask      X Y Z
0   00000000      N N N
1   00000001      Y N N
2   00000010      N Y N
3   00000011      Y Y N
4   00000100      N N Y
5   00000101      Y N Y
6   00000110      N Y Y
7   00000111      Y Y Y
Sortable table
Current Setting Invert X Invert Y Invert Z Invert X and Y Invert X and Z Invert Y and Z Invert X, Y and Z
0 (X=000, Y=000, Z=000) 1 2 4 3 5 6 7
1 (X=001, Y=000, Z=000) 0 3 5 2 4 7 6
2 (X=000, Y=010, Z=000) 3 0 6 1 7 4 5
3 (X=001, Y=010, Z=000) 2 1 7 0 6 5 4
4 (X=000, Y=000, Z=100) 5 6 0 7 1 2 3
5 (X=001, Y=000, Z=100) 4 7 1 6 0 3 2
6 (X=000, Y=010, Z=100) 7 4 2 5 3 0 1
7 (X=001, Y=010, Z=001) 6 5 3 4 2 1 0

(script for generating the above)

Grbl0.8 and earlier

$6 for Grbl 0.8, $7 for Grbl 0.7[13]

The values used are matched to the port pins[14] --- defaults for these are:

  • Invert X axis 32
  • Invert Y axis 64
  • Invert Z axis 128

To invert multiple axes, just add the values above together for the two axes.

For instance to invert X and Y, the value would be 96. For X and Z, 160.

Or wiring can be changed: see Direction in Assembly troubleshooting.

Sortable table
Current Setting Invert X Invert Y Invert Z Invert X and Y Invert X and Z Invert Y and Z Invert X, Y and Z
28 60 92 156 124 188 220 252

GRBL Calculator

GrblCalc screenshot

GrblCalc program for Windows by AtomSoft is a Grbl settings calculator based on the DrRob calculator here. The purpose of this program is to calculate values for Grbl settings based on parameters of a given machine and then upload those values in a few simple steps.

The GRBlCalc app is available at

Using Grbl

G-code supported by Grbl

See the list of G-codes here.

Compiling Grbl from Source (Advanced)

If you want to make modifications to the grbl source, you'll need to compile your changes into a hex file to run it on the Arduino. A lot of upgrades are in the pipes by the developers of grbl, but if you can't wait or want to implement a custom feature, this is the way to do it.

Instructions for compiling for multiple platforms are located on the grbl github wiki here

Carbide 3D 1.1 version:


There are multiple ways to compile grbl on Windows. You can use a standalone version of AVR-GCC that is packaged for Windows such as WinAVR (note that this is no longer supported and there is a PATH-deleting bug has been reported[15] --- instead try ), or use the version of AVR-GCC that is packaged as part of the Arduino IDE.

Using WinAVR to Compile


Using Arduino IDE to Compile


Streaming Grbl "glitch free"

A problem has been noted by several users that having the electronics on the same ac circuit as multiple other devices (spindle, fan, vacuum, or other) can cause electromagnetic interference with the usb connection and somehow cause GRBL to freeze midway during sending a file. Clean routing of wiring is also suggested to avoid this problem. Putting your USB cables in close proximity to AC cords is not recommended!

Startup Configuration

Grbl uses $N0 to store startup commands in the EEPROM.[16]

Height/Depth Probing

GRBL Height Probing Tutorial



30kHz step limitation[17] Rapid rates should be limited to 15,000.[18]

0.8 or earlier

Acceleration must match on all axes

This was discussed in Re: Z skipping steps- How to Slow Down Z Axis? where cvoinescu noted:

  1. You can use a version of GRBL that supports different speed and acceleration settings for each axis, such as the upcoming GRBL 0.9. However, last I checked that version was is still in development, so it may not work perfectly yet.
  2. You can use different firmware, such as Marlin or TinyG. Unfortunately, no other firmware runs on the Arduino Uno. Marlin requires an Arduino Mega 2560 and is not compatible with grblShield or the stepper shield without some hacking; and TinyG requires the TinyG board, which has a bigger and faster CPU than the Arduinos, so it won't run on one no matter what.
  3. You can refrain from using G0 "traverse" and always use G1 "feed" moves when the Z is involved, because G1 obeys the F parameter, so you can limit the speed. You'll have to configure your CAM, post-processor and/or g-code sender to do that (one Communication / Control program which will limit the Z-axis dynamically as it sends code is Zapmaker's Grbl_Controller). The acceleration limit is still shared between all axes, which is a bummer.
  4. Use an Acme screw on the Z axis. While this does not circumvent the limitation of the firmware, it allows the Z to move about twice as fast, so the limitation is less annoying. Even after you get a firmware/controller with separate axis configuration, the Acme screw is a great upgrade to have.

Line length limit

Please note that GRBL is limited in how long of a line it will accept. If your job is previewing correctly, but not running properly, check to see that line lengths are w/in its limits (50 for older versions, 70 for 0.8c dev or later) as discussed here.


Acceleration and Tuning

Discussion of this here, including notes on the junction deviation setting: and how it should be changed for use when laser cutting or 3D printing.


Originally released under the GPL, Grbl 0.8 has since been made available using a permissive MIT license.[20] 0.9 and later are GPL v3.[21]