Configuring Grbl v0.8
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:
$ (help)
$$ (print Grbl settings)
$# (print gcode parameters)
$G (print gcode parser state)
$N (print startup blocks)
$x=value (store Grbl setting)
$Nx=line (store startup block)
$S0 (toggle check gcode)
$S1 (toggle dry run)
$S2 (toggle block delete)
$S3 (toggle single block)
$S4 (toggle optional stop)
$P (purge buffer and locks)
$H (perform homing cycle)
~ (cycle start)
! (feed hold)
? (current position)
^x (reset Grbl)
Of these commands, ony four of them are used to configure Grbl [$SS, $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:
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=314.000 (x axis, steps/mm)
$1=755.906 (y axis, steps/mm)
$2=755.906 (z axis, steps/mm)
$3=30 (step pulse, usec)
$4=500.000 (default feed rate, mm/min)
$5=500.000 (default seek rate, mm/min)
$6=0.100 (arc resolution, mm/segment)
$7=28 (step port invert mask, int:binary=00011100)
$8=50.000 (acceleration, mm/sec^2)
$9=0.050 (cornering junction deviation, mm)
$10=0 (report inches, bool)
$11=0 (auto start enable, bool)
$12=0 (invert stepper enable, bool)
$13=0 (hard limit enable, bool)
$14=0 (homing enable, bool)
$15=0 (homing dir invert mask, int:binary=00000000)
$16=50.000 (homing feed rate, mm/min)
$17=250.000 (homing seek rate, mm/min)
$18=100 (homing debounce delay, msec)
$19=1.000 (homing pull-off travel, mm)
$20=25 (stepper idle lock time, msec)
$21=3 (decimal places, int)
$22=25 (n arc correction, int)
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.
$Nx 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 one block of g-code as a system default, but it can store up to 5, as a compile-time option (changing config.h and re-compiling).
So, when connected to Grbl, type $N and then enter. Grbl should respond with something short like $N0= followed by an 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. (If you re-compile to enable more startup blocks, $N1 is the next line to be run, then $N2, and so on, up 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, G21 inches mode, G17 XY-plane. You would type N0=G21 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=G21G54G17.
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]
G21G54G17ok
If you have multiple g-code startup blocks, they will print back to you in order upon every startup.
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 turns per mm 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)/turns_per_mm
Compute this value for every axis and write these settings to Grbl.
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.
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.
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.
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 X_STEP_BIT 2
#define Y_STEP_BIT 3
#define Z_STEP_BIT 4
#define X_DIRECTION_BIT 5
#define Y_DIRECTION_BIT 6
#define 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)
This is the acceleration in mm/second/second. You don’t 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.
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.
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 $10=1 command, you send this boolean flag to true and the status reporting feature will now report in inches. $10=0 to set back to mm.
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 $11=0 command.
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 $12=1.
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 $13=1. That's it. 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.
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.
To set up how your homing cycle behaves, there are more settings down the page describing what they do.
Also, one more thing to note, when homing is enabled. Grbl assumes (at the moment) that you will perform a homing cycle everytime you startup your machine, so it will lock out all axes movement until you do. 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. :)
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.
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.
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.
Whenever a switch triggers, some of them can have electrical/mechanical noise that actually 'bounce' the signal high and low for a few microseconds 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 microseconds is fine.
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.
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, you can keep all axes always enabled by setting $20=255.
Set how many decimal places all of the floating point values Grbl reports. Not much more complicated than that.
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 small angle approximation. N-arc correction is the number of arc segments performed before Grbl computes and moves to the exact location for the next arc. 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 arc, but it's not recommended to go below 3 because this can lead to buffer starvation (the axes slow down and hiccup).
- DANK Last updated 2/2011. Only applies to grbl v0.6.