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.
- 1 Overview
- 2 Downloading
- 3 Commands for Grbl
- 4 Editing for Buildlog.net Stepper Shield
- 5 Notes on using Grbl with Synthetos Grblshield
- 6 Installation and configuration
- 7 Configuring Grbl
- 8 Using Grbl
- 9 Compiling Grbl from Source (Advanced)
- 10 Streaming Grbl "glitch free"
- 11 Startup Configuration
- 12 Height/Depth Probing
- 13 Limitations
- 14 Simulation
- 15 Acceleration and Tuning
- 16 Licensing
- 17 References
(from https://github.com/grbl/grbl) 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. 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 (http://bengler.no/grbl) 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: https://github.com/grbl/grbl/wiki/Configuring-Grbl-v0.8#grbls-xval-settings-and-what-they-mean
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: http://arduino.cc/en/Tutorial/ArduinoISP 
Github instructions here: https://github.com/grbl/grbl/wiki/Flashing-Grbl-to-an-Arduino
There are two different files to download.
- Hex file - The code that'll run on the Arduino. Download from github repository here
- 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 auduino.cc. 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 buildlog.net:
General Hex Files:
- The complete set of hex files are available from the GRBL project on github
- Or you can download the source and compile the hex file yourself.
This is the newest version, linked to from the Grbl main page:
Instructions on upgrading: http://www.shapeoko.com/forum/viewtopic.php?f=3&t=7676&p=60641
Grbl 0.9g (Shapeoko 3)
There is a copy of Grbl w/ defaults for the Nomad883 at: http://carbide3d.com/files/grbl.hex --- the settings should be adjusted to match: http://docs.carbide3d.com/article/38-shapeoko-3-default-grbl-settings 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.
Shapeoko 2 Hex File
Note that it may be necessary to clear any coordinate offsets or other persistent settings when upgrading.
- Make a copy of your current settings. I simply took a photo of my screen showing the settings ($$).
- Made certain I knew which port my SO was running on.
- Downloaded the hex file from github for the SO2, I am presuming you have a stock setup.
- Download a program for flashing (Windows: XLoader, Mac OS X: HexUploader, Linux: Easy Flash script) also from github and extract the file.
- 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.
- 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.
- 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.
- 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.”
- 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).
A basic one for the stepper motors is shown as part of the assembly instructions: http://docs.shapeoko.com/electronics.html
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 
~ resume cycle
Editing for Buildlog.net Stepper Shield
Using the buildlog.net 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_DDR DDRB #define STEPPERS_DISABLE_PORT PORTB #define STEPPERS_DISABLE_BIT 0 #define STEPPERS_ENABLE_DDR DDRB #define STEPPERS_ENABLE_PORT PORTB #define STEPPERS_ENABLE_BIT 0 #define STEPPERS_ENABLE_VAL 0 // 0=low 1=high #define STEPPING_DDR DDRD #define STEPPING_PORT PORTD #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 #define SPINDLE_ENABLE_DDR DDRB #define SPINDLE_ENABLE_PORT PORTB #define SPINDLE_ENABLE_BIT 2 #define SPINDLE_DIRECTION_DDR DDRB #define SPINDLE_DIRECTION_PORT PORTB #define SPINDLE_DIRECTION_BIT 3
Stepper.c (insert this text on line 276):
// set enable pin if (STEPPERS_ENABLE_VAL) STEPPERS_ENABLE_DDR &= 1<<STEPPERS_ENABLE_BIT; // bit low is enable else 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_DDR DDRB #define STEPPERS_DISABLE_PORT PORTB #define STEPPERS_DISABLE_BIT 0 #define STEPPING_DDR DDRD #define STEPPING_PORT PORTD #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 #define SPINDLE_ENABLE_DDR DDRB #define SPINDLE_ENABLE_PORT PORTB #define SPINDLE_ENABLE_BIT 4 #define SPINDLE_DIRECTION_DDR DDRB #define SPINDLE_DIRECTION_PORT PORTB #define SPINDLE_DIRECTION_BIT 5
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. http://www.synthetos.com/wiki/index.php?title=Z_Axis_Mod_for_Shapeoko#Z_Axis_Mod_for_Shapeoko
Installation and configuration
Notes on installing Grbl on a MEGA2560 in the forums: GRBL on Mega2560 - Solution.
- Upload to Uno with Arduino IDE
- Compiling Grbl
- Flashing grbl to Arduino, clear EEPROM --- before upgrading Grbl, one should erase the EEPROM of settings from the previous version.
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)
- To Determine your arduino's COM port:
- 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 http://arduino.cc/hu/Main/Software 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:
- 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:
- 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.
- Mac: see here
- How to flash grbl to your Arduino (Tutorial)
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
$0=87.489 $1=87.489 $2=320 $3=30 $4=750 $5=1100 $6=0.1 $7=0 $8=9.8 $9=0.05
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.
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.,
$130=415.000 (x max travel, mm) $131=430.000 (y max travel, mm)
840mm works well for a Shapeoko XXL.
$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.
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
|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|
Grbl0.8 and earlier
$6 for Grbl 0.8, $7 for Grbl 0.7
The values used are matched to the port pins --- 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.
|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|
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 https://github.com/AtomSoftTech.
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
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 --- instead try http://www.atmel.com/tools/atmelavrtoolchainforwindows.aspx ), 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!
Grbl uses $N0 to store startup commands in the EEPROM.
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:
- 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.
- 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 buildlog.net 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.
- 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.
- 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: http://www.shapeoko.com/forum/viewtopic.php?f=3&t=6970&p=54904#p54904 and how it should be changed for use when laser cutting or 3D printing.