From ShapeOko
Revision as of 14:28, 17 August 2012 by Jsbannis (Talk | contribs) (GRBL Calculator)

Jump to: navigation, search


(from 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 tool offsets, 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 20 motions into the future and plan its velocities ahead to deliver smooth acceleration and jerk-free cornering.

Important note for Atmega 168 users: Grbl used to be compatible with both the older Ardunios running atmega 168 and the newer with 328p. The full version of Grbl now compiles without support for circles/arcs if you target 168. If you need arcs, but not acceleration-management I am still maintaining Grbl 0.51 in the branch called ‘v0_51’.

Note for users upgrading from 0.51 to 0.6: The new version has new and improved default pin-out. If nothing works when you upgrade, that is because the pulse trains are coming from the wrong pins. This is a simple matter of editing config.h – the whole legacy pin assignment is there for you to uncomment.

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


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:

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.
Grblshield is compatible with grbl version 0.6 using a special, patched release.
Grblshield is not compatible with grbl version 0.5

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. 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


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.

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.

$7 Invert Bits

  • 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, $7 would be 96. For X and Z, 160.

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.

Download it from here.

Using Grbl

G-code supported by Grbl

In G-code, each "action" (modal group) should be on a separate line.

Grbl accepts coordinates in various forms ("0", "0." and "0.0000" are all ok), but some CNC machines require a decimal point to follow the number, which is why you'll see things like "0." in G-code.

The "meaning" in the table below may be an over-simplification... The whole table is a Work In Progress...

G-code Meaning Notes
G0/G00 Switch to rapid linear motion mode (seek) Used to get the tool somewhere quickly without cutting
G1/G01 Switch to linear motion at the current feed rate Used to cut a straight line
G2/G02 Switch to clockwise arc mode
G3/G03 Switch to anti-clockwise arc mode
G4/G04 Dwell (pause)
G17 Select the XY plane (for arcs)
G18 Select the XZ plane (for arcs)
G19 Select the YZ plane (for arcs)
G20 After this, units will be in inches Best practice: do this at the start of a program and nowhere else
G21 After this, units will be in mm Best practice: do this at the start of a program and nowhere else
G28 Return to home position (to-do: compare with G30)
G30 Return to home position (to-do: compare with G28)
G90 Switch to absolute distance mode Coords are now relative to the origin of the currently active coordinate system (to-do: explain!)
G91 Switch to incremental distance mode Coords are now relative to the current position
G92 Change the current coordinates without moving e.g. "G92 x0 y0 z0" makes the current position the home position
G93 Set inverse time feed rate mode (to-do: find out what that means)
G94 Set units per minute feed rate mode (to-do: find out what that means)

G-code examples

G2 - clockwise arc

G2 Xx Yy Ii Jj


  • I and J are relative to the current position, but X and Y may not be (depends which of G90 or G91 modes is selected)
  • If (i,j) isn't half way along a straight line from the start position to (x,y), the move will still begin with an arc of a circle (not an ellipse), and it will be followed by a straight line move to (x,y)

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