Credit by Graham

A guide to what GCode is on a Grbl based router, how does it work, what does it do and how to read, modify, and if necessary, write simple programs. It’s not intended to be a tutorial on how to write it; this is just an introduction to the basics.

There are lots and lots of tutorials, introductions and descriptions out there however they tend to be broad descriptions covering lots of different routers, including many commands unsupported by Grbl. This one is aimed specifically at users of Grbl based systems.

Changes from V1.0

• The format has been revised to a ‘blog’ style, whatever that is but I am told it is trendy!
• Added a rotary 4 th or A Axis.
• Some Minor rewording and corrections.
• Some Major rewording, extra sections, corrections and clarifications. It’s amazing what an extra 2 ½ years playing with these routers will do and how much they have changed!

What is Gcode

The router understands a set of commands called Gcode (Geometric Code, first developed in the late 1950s, that’s over 60 years ago!) which control the motion, speeds etc. of the spindle allowing accurate and repeatable machining. It is defined in multiple standards (https://en.wikipedia.org/wiki/G-code) but nobody paid much notice to the standard other than as a basic core. Manufacturers of CNC (Computer Numerically Controlled) machines used the core concepts but developed their own extensions and implementations. So nowadays it is more like a set of guidelines ultimately dependant on the specific router it is implemented on, think of it as English with a lot of dialects and not all words have exactly the same meanings, not all meanings use the same words.

Gcode is a series of instructions which tells the router Left a bit, go faster, right a bit, go down, go slower..... The best analogy I have is like the instructions a human brain sends to the hands when they are turning the knobs on a 3 dimensional Etch-a-Sketch!

When your CAM software takes a tool path it has generated and turns it into Gcode it passes it through a post processor specific to which Gcode dialect your Router understands. Some specifically allow you to select a post processor, others rely on settings in the machine configuration but the process is the same. Selecting the wrong post processor or machine will cause problems and errors when the Gcode is sent to the router.

What is Grbl?

When Simen Svale Skogsrud first sat down and wrote Grbl in 2009, 14 years ago, he named it after a bigger version of a computer mouse. It’s small, useful, and doesn’t do much other than what it’s designed to do. So, if you ask him, it’s pronounced as “gerbil”.

This is the software which runs on the router motherboard; it basically takes Gcode commands and translates them into the electrical impulses to the motors that control movements and speeds. Grbl is free to use open-source software.

This guide is based on Grbl Version 1.1. but there are a large number of variants of this release. At the time of writing this is the overwhelmingly common version you are likely to be using, unless you have an older controller board. When a specific version of Grbl is built there are a number of options the builder must specify, this can change some of the functions but I have included the overwhelmingly common ones here.

Over the Past few years, the platform on which Grbl runs has changed, originally it was designed for an 8-bit Arduino processor with limited memory, now versions which run on 32-bit processors are common. But the basic Gcode is the same, however other features have been added.

Grbl also understands commands to jog the bit around, change settings... and will also report back how it is doing and what is happening. These are outside of the Gcode framework but are also described in this guide.

The router receives these commands one line or block at a time over a serial communications link, normally from a PC or other device such as an offline controller. NOTE: in Grbl based systems the offline controller often uses the same serial port as the USB connection, just using a different cable and socket. This is one reason why you cannot have an offline controller and USB connection active at the same time. Another reason is that for reliability you cannot have two separate sources for commands running at the same time.

NOTE: Grbl runs on a microprocessor which uses a number of outputs to control things like stepper motors, Spindle motors, Lasers..... It also has a number of inputs which are used for things like connecting limit switches, door switches..... If your router Main Board either does not expose these inputs and outputs or if they are not connected to anything the use of the feature becomes irrelevant! Obvious examples are limit switches, the use of a safety door open input and coolant/air assist control output. Even though Grbl supports them they will do nothing if not connected.

The options available in the Grbl you are using also depend on a number of build options which are selected by the manufacturer of your board and the version they are using.

Gcode File Format

It’s a text file, very simple, can be displayed and edited by any text editor, the file extension can vary from .nc, .txt, .tap, .gc, ..... while the file type may be different, it’s set by the software which creates the file and recognised by the software that is going to read it, the contents of the files will always be the same.

But (there’s always a but!) there are lots of standards for text files; the most important is how the end of each line is marked. Different operating systems use a different format of text files. The most common formats are Unix/Mac and Windows format. The difference is that on Unix/Mac, it’s just a LF character (\n). On Windows, it’s a sequence of two characters, CR and LF (\r\n).

Grbl recognises both but your Gcode Sender or Offline controller may only recognise a specific format.

A likely, but very broad, convention for a Gcode file is:

• Comment header describing what the file does and how to set it up. (Normally omitted whenyou need to find out what bit you are supposed to use)

• Setup of basic modes. Normally set once at the top of the file but can be changed at anytime. But a file is unlikely to switch from using units of mm to units of inches in the middle!

• Movements with Speeds and Feeds
• End of Program, it may just stop or could move the bit somewhere first.

Gcode Line/Block Format

Separate from the file format, what does each line look like? A line is also be referred to as a Gcode block.

When processing a line first Grbl ignores all spaces and tab characters, converts all characters to upper case and ignores any blank lines so all the following are treated identically:

• G1 X4 Y7
• G1X4Y7
• G1X4   Y     7
• g 1x 4 Y7

Commands and parameters normally consist of a letter followed by a number, for example G is a general command followed by a numerical value, 0 indicates a positional move. The number is converted from all digits until a new command letter is found so the following are treated

identically:

• G1
• G01
• G01.0
• G000001
• g 0 00 1

(remember spaces are removed and letters converted to uppercase)

G0001.001 would not be the same as the number is does not resolve to 1 but 1.001

Commands can (as long as they don’t share parameters or conflict with each other) be specified on the same line, the order that they appear on the line is not important. Obvious conflicts would be placing a cutting move (G1) and a non cutting move (G0) on the same line, like a drill sergeant shouting place your left right foot forward. So, all the following have the same effect:

• G90G20G0X1
• G20 G90 G0 X1
• X1 G20 G90 G0
• G90 G0 G20 X1

Comments

There are two types of comment in Gcode, a ‘;’ indicates that the rest of the line is a comment.

Comments can also be placed within round brackets. The comment starts with a ‘(‘ and is ended by the first ‘)’ encountered or the end of the line.

Nested comments like (this is a (comment) and so is this) are NOT supported the first ‘)’ will terminate the comment and then the ‘and so is this)’ will be processed as normal but will generate an error as it’s not valid Gcode. However, something like ‘G0 (positioning move) X3 (move 3mm)’ is valid and will be processed as ‘G0 X3’.

Do not use the ‘;’ comment within brackets to try and comment the rest of the line out, it will be ignored as being part of the original comment!

Modal vs non modal commands

Modal commands set a mode; a mode is remembered for all subsequent commands until explicitly changed. Non modal commands apply only to the line in which they are contained and are not remembered for any subsequent lines.

For example, Snnn sets the spindle speed to nnn; it is a modal command so will be remembered until

changed.

So:

G1 X1 Y1 S1000

G1 X2 Y2 S1000

And

G1 X1 Y1 S1000

G1 X2 Y2

And

S1000

G1 X1 Y1

G1 X2 Y2

Behave identically.

The movement type G1, G0... is also a modal command so

G1 X1 Y1 S1000

X2 Y2

Will also remember the G1 mode for the second line.

When Grbl is started or reset then it sets and loads defaults for all modes.

Persistent commands and parameters

Some values when changed are stored in the onboard EEPROM, just as all the $ settings are. These values will persist even after a reset or power cycle. This can be useful but also be an annoyance if you don’t understand what is happening.

This is different from Modal commands and values which although saved will be reset to the defaultvalue on a reset or power cycle.

Any Persistent position is saved using machine coordinates, so is reliant on a homing cycle having been run to set an accurate machine origin. If the command uses other coordinates, they are translated to machine coordinates before being saved. These only make sense with a consistent machine zero position, i.e. your router has limit switches and a homing cycle has been has been performed. If you don’t have limit switches or don’t run homing the results will be random as the machine zero position will be whatever the XYZ coordinates were when the router was last powered on or reset.

If you change the Machine home position, this could be by altering the homing parameters such as $23 or $27, these saved values will be incorrect. Also changing something like the spindle motor for a laser, which although it will not affect the machine coordinate zero points, will change the effective position of the ‘bit’ at the machine zero position.

The following command parameters are persistent

• G10 L2   Set Saved origin offset using absolute machine coordinates.

• G10 L20  Set Saved origin offset using offsets from the current position.

• G28.1   Set ‘Safe’ position using absolute machine coordinates.

• G30.1   Set a predefined position using absolute machine coordinates.

A Zero position offset set by the G92 command IS NOT persistent.

These persistent values can only be erased or altered by directly changing them, for example a G10L2 X0Y0Z0, or by using the $RST=# or $RST=*, one command to clear them all!

Commands and Parameters

Some commands have parameters, some don’t. For example, G0 is a movement command and uses the parameters of the new positions of the axes; Xnn, Ynn, Znn and Ann. Not all have to be specified, the ones that aren’t specified will just be taken as no change. G21 sets the units in the following Gcode commands for the XYZ axis to mm and has no parameters.

You cannot have two commands on the same line which share the same parameters, even if they are not specified, and cannot have multiple identical parameters on the same line as the parser gets confused and so will return an error. For example

G0 X1 G1 will create an error as it’s ambiguous to the parser as to what command the X applies to. It will also object to more than one different movement commands on the same line.

G0 X1

G1 X1

On separate lines is not ambiguous.

G0 X1 X2 will also create an error for similar reasons.

Absolute and Relative coordinates

Relative coordinates are the position reached or set by moving a distance from the current position.

X1 is one unit to the right of the current position.

Absolute coordinates ignore the current position and the position reached or set is from an absolute offset from either the Machine or Work Coordinate zero point. X1 is one unit to the right of the Origin.

G90 means use absolute coordinates, G91 means use relative coordinates.

G90 X1 and G91 X1 will produce vastly different movements!!

Positive and negative movements and spaces

In Grbl a movement to the Left, Down or to the front is a negative movement.

A relative movement of X-10 will move 10 units to the left, X10 would move 10 units to the right. An absolute movement of X-10 will move 10 units to the left of the WCS origin, X10 would move 10 units to the right of the WCS origin.

If you have set the work origin at the front left bottom of the stock then all movements through the stock will be in a positive space, all absolute coordinates will be positive.

If you set the work origin at the back right top of the stock then all movements through the stock will be in a negative space, all absolute coordinates will be negative.

Depending on the position of the origin the movements can be in a mixed, positive or negative

space.

Coordinate systems

There are two complimentary coordinate systems used in Grbl.

Machine Coordinates

The origin or zero points of the Machine coordinates are initially set by the position of the spindle when the router is powered on. In this case the machine origin really has no practical meaning as it is not going to be consistent.

If the router is configured to perform a homing cycle by seeking out limit switches on the XYZ axes (The AB rotational axes are not homed) according to the homing settings. Running a homing cycle will reset the Machine Coordinate Origin to a known and consistent point.

The values you will see depend on the homing parameters; $23 sets the corner into which the machine will home (Top Front Left is or $23=3)

Some Grbl builds will set the home position at the point the switch is triggered, which means the position after homing will be the $27 pull-off value, others set the zero position after the pull-off has been performed which means the homing position will be zero.

If homing is enabled the machine may be placed in an Alarm state on a power on or reset to indicate that the Machine Coordinates have not yet been set. This can be cleared by running a homing cycle or just unlocking the machine which will leave the Machine coordinates as they were but place the Machine into an Idle state.

There are some options which are not sensible to use unless the Machine coordinate origin will be consistently set by a successful homing cycle. These rely on the Machine coordinates being in a known and consistent position. An example is the G28 ‘Safe’ position which uses absolute machine coordinates. If the machine origin has not been set then this will be an ‘Unsafe’ position!

Normally within a Gcode file all the movements it will use will use to the Work Coordinates, not the Machine coordinates so while it can be useful homing is not required.

Work System Coordinates

Also referred to as WCS (Work Coordinate System), Work coordinates or Local coordinates.

These set the coordinates for all your jobs. When you zero the origin of the axes before starting a job, you are setting the origin of the Work Coordinates and all moves will then be based from this

origin.

Grbl supports 6 separate Work System Coordinate sets (G54-G59 G54 is the default). The origin of these can be set separately and can be saved permanently until changed, this would allow a machine to be set up with a number of fixed clamps or fixtures with a different origin set and saved for each, allowing multiple parts to be cut using the same Gcode without having to set the origin manually for each. Just change the Work System Coordinates in operation by a G54-G59 command which activates the relevant Work Coordinate Origin.

To save the coordinates for these you must have performed a homing cycle as their coordinates are based on offsets from the Machine origin coordinates. Using multiple WCS origins is outside the scope of this guide as 99.9% of users will never use them, they are mentioned briefly in case you encounter them. But they are not difficult to use.

Axes

X, Y and Z are the 3D axes (X left and right, Y front and back and Z up and down). Movements on these are in mm or inches.

If you are using a rotary axis then the A axis is rotation about the X axis, B axis is rotation about the Y axis. Movements and positions on AB axes are always in degrees. Looking at the front of a rotary axis + is clockwise, - is anticlockwise.

Gcode Senders

Not part of Grbl but the Gcode sender you use can affect things. For example, UGS will remove all blank lines and comments BEFORE it sends the code to Grbl. Also, there can be differences in the way that WCS origins are set, using either G10 or G92 commands.

Your sender can also have startup commands which it will send to the router …….

Supported Commands and Parameters

Not everything that is Gcode is supported within Grbl. Some are archaic, some have been introducedfor 3D printers, and some are for features that Grbl does not have the capacity to execute such asautomatic tool changers. Others may be supported but are for features which are normally not found on small hobby routers such as anti-clockwise spindle rotation.

NOTE: In the tables below a default mode for a modal command is the one in operation after a power on or reset of the router Main Board.

Line Numbers

These are not normally used but you may see them, they are ignored by Grbl.

Measurement units

NOTE: What units Grbl uses to report positions etc. back to the Gcode sender is set by a Grbl parameter ($13) and will be unaffected by these commands.

Coordinate mode

Coordinate mode

Feed Rate Mode

Feed Rate

If the Feed rate specified exceeds the parameter value in the Grbl settings for Maximum feed rate on any axis in a movement command the parameter value will be used.

Note: Changing the Units (G20/G21) when a feed rate is already set without adjusting for the new units will have unintended consequences.

Note on Feed and acceleration

When Grbl needs to change the direction of the spindle to start a new motion it will decelerate the spindle in each axis to allow it to change the direction cleanly and then accelerate the speed of the motion until the requested feed rate is reached.

If you are making a number of small movements for example, drawing in a circle is often broken down into a lot of small movements in straight lines, then the requested feed rate may never be reached before it starts to decelerate before the next direction change. These movements may often be much slower in practice than the feed rate specified.

The acceleration rates used can be adjusted (with caution) by Grbl parameters.

Spindle Speed

The actual spindle speed Snnnn value will be ‘adjusted’ if necessary, by the Grbl $30 and $31 settings values for maximum and minimum speeds. If the maximum speed of your spindle motor is 10,000 RPM setting a higher speed will not make it turn faster. When running a Laser, the power is determined by the percentage calculated from the Grbl $30 setting for maximum Spindle speed.

Note on Spindle Speed and acceleration

When Grbl is told to change the spindle speed it will pause for a short while to allow the spindle motor to reach the new speed before continuing, this cannot be adjusted. When Laser mode is enabled, these pauses are not used as the change in Laser power will be nearly instantaneous and pausing would result in over burning at that point.

Spindle Control

NOTE: M2 and M30 which are program ends will also stop the spindle.

Motion – Lines

Motion – Arcs

How to draw an arc

There are only 8 basic options! Well as long as the arc is drawn in the XY plane that is.

Two sets of 4 options each are for clockwise and anti-clockwise arcs, within each set using relative or absolute coordinates leaves 2 basic options, specifying the Arc by the use of the R parameter or the IJK parameters I J K correspond to the Z Y and X axes for setting the location of the centre point of the arc.

All these examples are using relative coordinates (G91 mode), Absolute coordinate mode (G90) can be used, but that would only affect the X Y end point coordinates which would just have to be translated into the absolute values, The I J and K coordinates in Grbl are always relative to the starting position and R is just a value.

The principles of drawing an arc are simple; It’s only the practice that is complex!

• An arc starts at the current location
• The direction the arc is drawn in is specified by G2 or G3
• The arc has a fixed radius• The location of the centre point of the arc is specified by either stating the radius I OR by the always incremental coordinates of the centre point (I J K) from the starting position. You cannot use any of IJK and R in the same arc command.
• The arc stops when the XYZ coordinates in the G2/3 command is reached. If these are the same as the starting position a full circle will be drawn.
• Two X Y Z parameter values must be specified corresponding to the axis plane even if they are zero.
• Some implementations of Gcode support a P parameter for arcs to specify the number of rotations to be made, Grbl does not.

Arc Examples

A simple arc to give a rounded corner as in the picture.

The Gcode using IJK would be

G2 I0 J-2 K0 X2 Y-2

The Gcode using R would be

G2 R2 X2 Y-2

Stopping the Arc using XY coordinates can cause problems, what if the Arc never crosses the end coordinates? Well you get errors!

What if this was the desired result, very similar but totally different. The cut is going to be anti-clockwise and the centre point of the arc is different.

The Gcode using IJK would be

G3 J0 K2 X2 Y-2

The Gcode using R would be

G3 R2 X2 Y-2

But what about?

The right two cannot be specified using just an R coordinate, they would have to be specified using IJK coordinates. This is normally true of any full circle as the end point is the same as the start point and so no information can be gleaned by Grbl as to how the circle should be drawn.

As for the one on the left unfortunately I am writing this on a Thursday, I don’t do maths on Thursdays! If you require more information there are plenty of tutorials available online and this is one of the reasons why computers and CAM programs were invented!

An arc can also be broken down into a lot of small straight lines, I believe this is how Grbl actually draws them but the CAM software may also do this.

Probing

‘Normal’ use is using a Z-Probe but Grbl supports probing on the X, Y and Z axes. The axis parameters

signify the direction to move in and how far to move to find the probe.

NOTE: If you have soft limits enabled a limit violation will be generated if the maximum movement would

exceed a soft limit.

Arc Examples

A simple arc to give a rounded corner as in the picture.

The Gcode using IJK would be

G2 I0 J-2 K0 X2 Y-2

The Gcode using R would be

G2 R2 X2 Y-2

Stopping the Arc using XY coordinates can cause problems, what if the Arc never crosses the end coordinates? Well you get errors!

What if this was the desired result, very similar but totally different. The cut is going to be anti-clockwise and the centre point of the arc is different.

The Gcode using IJK would be

G3 J0 K2 X2 Y-2

The Gcode using R would be

G3 R2 X2 Y-2

But what about?

The right two cannot be specified using just an R coordinate, they would have to be specified using IJK coordinates. This is normally true of any full circle as the end point is the same as the start point and so no information can be gleaned by Grbl as to how the circle should be drawn.

As for the one on the left unfortunately I am writing this on a Thursday, I don’t do maths on Thursdays! If you require more information there are plenty of tutorials available online and this is one of the reasons why computers and CAM programs were invented!

An arc can also be broken down into a lot of small straight lines, I believe this is how Grbl actually draws them but the CAM software may also do this.

Probing

‘Normal’ use is using a Z-Probe but Grbl supports probing on the X, Y and Z axes. The axis parameters

signify the direction to move in and how far to move to find the probe.

NOTE: If you have soft limits enabled a limit violation will be generated if the maximum movement would

exceed a soft limit.

At the end of the probe command the current coordinates can be used to set values such as the zero position in Work Coordinate System.

Work Coordinate System Origins and offsets

L strictly speaking is a parameter to the G10 command, Grbl only accepts L2 and L20 so I have documented them as separate commands.

Stop and Pause (or Dwell)

* A lot of other systems implement the P parameter using seconds, Grbl uses milliseconds.

Coolant Control and Air Assist)

Grbl supports these commands if enabled in the Grbl Build options. What they do is turn on and off an output pin on the control board which can control a relay to turn something on and off. These commands can control a coolant system but they are more likely to control an air-assist pump when using a Laser. Many boards do not expose these pins.

Supported Commands to prevent errors

These are a set of unrelated commands that won’t cause unrecognised Gcode command errors but do nothing. Support seems to be included to prevent the use of them generating errors when they are just present, normally this would be in the setup area of a Gcode file at the start.