Non classé

Installation of the GRBL ESP32 software

Written by Avataar120

This tutorial covers the installation of GRBL ESP32 even if you have not purchased my laser shield.
However, the chapters on settings will be adapted to my shield, you will have to make changes if you use another shield !

Compiling GRBL ESP32:

Preparation of the compilation environment

  • Install the latest version of the Arduino IDE (lien)
  • Download the latest version (version >= 871 otherwise USB stability pb) of GRBL ESP32 (link), if you are not familiar with Github follow the instructions below :
    • Click on the green “Code” button
    • Choose “Download Zip”
    • Unzip the zip in the directory of your Arduino projects (usually Documents/Arduino)
  • Install the necessary libraries:
    • Two are provided in the zip of GRBL ESP32 : ArduinoWebSockets and ESP32SSDP
      Copy the two libraries (located in the unzipped directory in the “libraries” directory in the arduino libraries directory on your PC : usually in Documents/Arduino/libraries
    • The third TMCStepper must be installed via the library manager of the arduino IDE :
      Menu Sketch/Include Library/Manage Libraries (or CTRL+SHIFT+I)
      Search for TMCStepper and add it by clicking on install
  • Install the ESP32 board files in the Arduino IDE :
    • In the menu File/Preferences, put the line in the line “Additional card manager URL” and click OK
    • In the menu Tools/Card type/Card manager, search for ESP32 and install the associated manager with version <= 1.0.4 (version 1.0.5 and 1.0.6 have a bug on the serial over USB connection)
    • In the menu Tools/Type of board/ESP32 Arduino, choose “ESP 32 Dev Module”.
    • In the menu Tools/Map Type/Partition Scheme, choose “Minimal SPIFFS”.
    • Your setup should look like this:
GRBL ESP32 - Configuration IDE Arduino

Setting up GRBL ESP32:

This software has been designed to drive many different machines and in particular CNC and laser machines.

It is therefore necessary to modify some parameter files before compiling GRBL ESP32.

Configuring your machine :

In the unzipped directory containing GRBL ESP32, go to the GRBL_ESP32/src/Machines directory

Create a file named “K40_AvaShield.h” for example

Include the following lines (if you have my shield, otherwise it will be necessary to adapt)

#define MACHINE_NAME            "K40_AvaShield" //Name your machine

#define X_STEP_PIN              GPIO_NUM_12
#define X_DIRECTION_PIN         GPIO_NUM_14
#define Y_STEP_PIN              GPIO_NUM_26
#define Y_DIRECTION_PIN         GPIO_NUM_15
#define Z_STEP_PIN              GPIO_NUM_27
#define Z_DIRECTION_PIN         GPIO_NUM_33

#define X_LIMIT_PIN             GPIO_NUM_17
#define Y_LIMIT_PIN             GPIO_NUM_4
#define Z_LIMIT_PIN             GPIO_NUM_16

#define SPINDLE_TYPE            SpindleType::LASER

#define COOLANT_MIST_PIN        GPIO_NUM_21  // labeled Air_Assist

#define COOLANT_FLOOD_PIN       GPIO_NUM_25  // labeled Coolant
#define PROBE_PIN               GPIO_NUM_32  // labeled Probe

#define DEFAULT_HOMING_CYCLE_0   ((1<<X_AXIS)|(1<<Y_AXIS))
#define DEFAULT_HOMING_CYCLE_1   (1<<Z_AXIS) //Only if you have a motorized bed
#define INVERT_LIMIT_PIN_MASK 	 (bit(X_AXIS)|bit(Y_AXIS))

#define DEFAULT_INVERT_SPINDLE_ENABLE_PIN 1 //The K40 power supply fires the laser on a low state. If your power supply fires on high state, do not put this line


#define CONTROL_SAFETY_DOOR_PIN GPIO_NUM_35  // labeled Door, can be a problem on some versions of ESP32
#define CONTROL_RESET_PIN       GPIO_NUM_34  // labeled Reset,
#define CONTROL_FEED_HOLD_PIN   GPIO_NUM_36  // labeled Hold, 
#define CONTROL_CYCLE_START_PIN GPIO_NUM_39  // labeled Start,

Be careful, the PIN safety DOOR can prevent you to communicate via the serial link with GRBL as long as the ESP32 is not on the shield (not systematic and depends on the ESP32)
Two possibilities:

  • Comment the line #define CONTROL_SAFETY_DOOR_PIN … the time to make your settings if you have not yet assembled your shield, then uncomment it when you have your shield
  • Install the ESP32 on its shield as soon as the software is downloaded via the Arduino IDE (see below)

Integration of this file into the ESP32 project:

Modify the machines.h file located in the GRBL_ESP32/src/ directory to include the settings file we just created:

Under the directive: #ifndef MACHINE_FILENAME, replace the #include “Machines/test_drive.h” with :

#include "Machines/K40_AvaShield.h" //modify name to match the file name you created just above

Modification of the general parameters of GRBL ESP32:

There is no SDCARD on the Shield v2
if you have this version of the shield, please comment this line : #define ENABLE_SD_CARD :

Please also check if communication rate is set up to 115200 bauds

//#define ENABLE_SD_CARD (only if you are using shield v2)
#define BAUD_RATE 115200

Compiling GRBL ESP32:

There is almost nothing left to do!

Open the GRBL_ESP32/Grbl_Esp32.ino file in the Arduino IDE (File/Open)

And click on the “Check” icon

The compilation may take a few minutes.

If all goes well, you should only get compilation warnings (especially if you have several libraries installed for some modules). The final message should look like this:

Le croquis utilise 1824342 octets (92%) de l'espace de stockage de programmes. Le maximum est de 1966080 octets.
Les variables globales utilisent 69252 octets (21%) de mémoire dynamique, ce qui laisse 258428 octets pour les variables locales. Le maximum est de 327680 octets.

Downloading GRBL ESP32 to the ESP32

All that is left to do is to upload the compiled software to the ESP32.

For this step, the ESP 32 must not be mounted on the shield.
It is not necessary either that a software using the serial port is launched (like lightburn for example)
Once the first SW is loaded in the ESP32, it will then be possible to update it ON the shield via the over the air update (via the web interface of GRBL ESP32) – see chapter OTA update below

Connect the ESP32 via a USB cable to your PC.
Check in the Tools/Port menu that a serial port is connected – if not, select the COM port displayed in the submenu.

Start the upload by clicking on the upload icon in the IDE
After a few seconds, you should have messages in the console indicating writes “Writing at 0x00xxx000…. (XX%)” and then the final message:

Wrote 3072 bytes (129 compressed) at 0x00008000 in 0.0 seconds (effective 2730.6 kbit/s)...
Hash of data verified.

Hard resetting via RTS pin...

At this stage, if you already have your shield, you can mount your ESP32 on the shield (don’t forget to disconnect the ESP32 from your computer beforehand so that it is not powered when you insert it in the shield)
No need to power the shield via an external power supply, the power supply via the USB port of your computer is sufficient to run the shield for all your settings / checks before mounting in the K40

Wifi configuration

You can already set your wifi parameters via the console of the Arduino IDE if you have chosen a standard communication speed for the BAUD_RATE in the config.h file.
Otherwise, you will have to do it via the WebUI console accessible in Wifi (Access point automatically created by GRBL ESP32 during the first installation, connection address

In the Arduino console, enter the following command :


You should see a list of all extended GRBL parameters (compared to the original version of GRBL, the ESP32 version allows to set many parameters after compiling GRBL)

Enter the following commands :

$Sta/Password=Your_very_very_secret_password (mini 8 characters)

Now press the “RESET” button next to the USB port on your ESP32 and you should see the following message in the console:

[MSG:Connected with]
[MSG:Start mDNS with hostname:http://grblesp.local/]
[MSG:SSDP Started]
[MSG:HTTP Started]
[MSG:TELNET Started 23]
[MSG:Flood coolant on pin GPIO(25)]
[MSG:Mist coolant on pin GPIO(21)]
[MSG:X  Axis limit switch on pin GPIO(17)]
[MSG:Y  Axis limit switch on pin GPIO(4)]
[MSG:Z  Axis limit switch on pin GPIO(16)]
[MSG:Probe on pin GPIO(32)]

Grbl 1.3a ['$' for help]

Your GRBL is now connected in Wifi and you can connect to the IP address provided by your router or via the address : http://grblesp.local/

You should see the following page:

Now you have to install the GRBL user interface.
For that, click on “Select. Files” and look for the file GRBL_ESP32/data/index.html.gz (provided in GRBL ESP32 project)

Then click on “Upload” and finally click on “Go to ESP32 Interface”.

This should take you to the GRBL web interface:

GRBL ESP32 configuration for the K40

The K40 is not equipped with standard stepper motors and standard pulleys.

Indeed, when the classic stepper motors are 1,8° per step, that is to say 200 steps for one turn, the motors of the K40 are twice more resolute with 0,9° per step, that is to say 400 steps for one turn

When the classic pulleys and belts are BT2 (each tooth is 2mm), on the K40, in general, there are MXL pulleys and belts whose pitch is 2.032mm
The pulleys have 20 teeth.

GRBL needs to know how many steps are needed to make one millimeter.

Depending on your chosen microsteps configuration (see article: new electronics for K40), the number of steps will be different:

Formula is simple : NbStepFor1mm = 400/40,64 * NbMicroStepPerStep

Number of microsteps for 1 stepNumber of steps for 1 mm

We will therefore enter these settings for the X and Y axis (depending on your choice of microsteps).
If you have chosen 4 microsteps for 1 step (i.e. 1/4th), here is what you will have to enter in the Arduino console or in the console of the web interface:


All that remains to be done is to set the accelerations, maximum speeds and authorized travel distances (speeds are in mm/min):




For the Z axis, if you have a motorized bed like the one of JP. Civade with 1/4 steps :


And now, some more general settings:

Don't put all that is between brackets :)

$Stepper/Pulse=10          (Pulse duration for one microstep)
$Stepper/IdleTime=250      (Hold the motors during this time. 255 for unlimited hold of the motors. Can generate heat on the motors or drivers)

$Limits/Invert=On          (Endstops are Normally Closed)
$Probe/Invert=On           (There is a pull-up for the PROBE - 0V for activated)

$Report/Status=2           (Very important when using a motorized bed. GRBL will give coordinates according to workspace instead of machine referential)

$Limits/Soft=Off           (To be activated if you want to stop the work in case of coordinates higher than the maximum coordinates given in X/MaxTravel and Y/MaxTravel)
$Limits/Hard=On            (Stops the work if the end positions are reached)

$Homing/Enable=On          (Activate homing feature)

$Homing/DirInvert=XY       (Reverse the homing direction of the X and Y axes - depends on your wiring, see article on the first power up)
$Homing/Feed=200.000       (Homing speed during the 2nd mvt - slow movement)
$Homing/Seek=2500.000      (Homing speed during the 1st mvt - fast movement)
$Homing/Debounce=25.000    (Time to validate a stop value change)
$Homing/Pulloff=5.000      (Withdrawal movement on all axes following a homing)

(Homing of the bed after homing XY. If no bed put $Homing/Cycle1=)

$GCode/LaserMode=On        (Activates the laser mode - which changes the behavior of GRBL on several subjects)

$Spindle/PWM/Frequency=15000.000 (PWM frequency driving the laser power)

Each command entered must be acknowledged by GRBL with an “ok”.

You can check that the parameters have been taken into account with the command :


You have now completed the installation of GRBL for ESP32! Congratulations!

Over the air update :

If it is not possible to upload a GRBL update for ESP32 via the Arduino interface if your ESP32 is mounted on the shield, it is however possible to update it over the air or OTA (via wifi) even if it is mounted on the shield.

To do this, you must first know where Arduino IDE stores the compiled GRBL software.
You have to activate the following options in the “File/Preference” menu:

Then, you just have to compile GRBL via Arduino IDE and at the end of the compilation, the directory containing the binary file to download via OTA is indicated


The binary file will be located in the directory c:\users\YourNameAppData\Local\Temp\arduino_build_XXXXX

Launch the WEB interface of GRBL via the IP address given by your router or enter http://grblesp.local/

Select the ESP3D menu and click on the orange cloud icon

It only remains to select the file Grbl_Esp32.ino.bin located in the directory previously mentioned

After the download, the ESP32 and the WEB interface restart by themselves.


If your ESP32 is not detected during the USB connection, it may be due to your USB driver.

Under Windows in particular, it may be necessary to reset the USB driver to an older version for the serial over USB link to work properly.

Link to the correct USB driver version : lien

About the author


Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.