Compiling with Arduino IDE
Important: When first programming the ESP32 with Grbl_Esp32, ensure that it is not attached to a controller shield. Any previous firmware could put pins in a state that damages the ESP32 when powered on. Program it unattached and verify the firmware via the USB first. Never plug in the ESP32 or any other items while powered on.
Install the ESP32 libraries from the boards manager in the Arduino IDE. Select version 1.0.3. Recent changes in 1.0.4 and above have bugs that prevent proper use in Grbl_ESP32.
Note: If you are using a machine definition that includes files from the Custom folder. You must compile using PlatformIO.
You must select the Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS) partition scheme under the Tools...Partition Scheme... menus, otherwise the firmware will not fit.
Use these settings
Download the main branch as a zip file or with Git (preferred). Do not alter the folder structure at all. The files must be in the proper folders.
Some libraries must be added to the Arduino IDE. Copy the folders in the Libraries folder to the libraries folder in your Arduino folder on your computer. Typically some folder like "...\Documents\Arduino\libraries" (Windows computer).
Note: Even if you are compiling a branch, it is best to copy the libraries from the main branch. The main branch is updated frequently to track changes in the latest Espressif Arduino Core.
TMCStepper library: Add the TMCStepper library to the Arduino IDE. Do this with the following menu clicks sketch...include libraries...manage libraries. Then search for TMCStepper and add the library. You need it even if you are not using Trinamic stepper drivers.
The firmware must be custom-compiled to match your system. Each shield has a specific connection of ESP32 pins to functions on the shield - stepper sockets, spindle controls, limit pins, etc. Futhermore, machines can use a shield in ways that do not match the labeling on the shield. The customization is done via a "Machine Definition File". There are preconfigured machine definition files in the Machines/ subdirectory. You can use one of them as-is if it is suitable for your machine, or you make a new one to match your setup. Once you have chosen or made a suitable file, you select it by editing the file "Grbl_Esp32/src/Machine.h" to "#include" your file.
Historical note: Older revisions of Grbl_ESP32 used a single "cpu_map.h" file to define all possible configurations in one file, with #ifdef lines to select a particular configuration. A line in "config.h" defined a machine name that drove the inclusion and exclusion of code within cpu_map.h. That was becoming unwieldy, so the cpu_map.h file was split up into separate files, one for each basic configuration.
The default setup is a test drive mode, selected by the line #include "Machines/test_drive.h" in Machine.h. It creates a virtual 3-axis machine that you can safely play with on an ESP32 dev module by itself or attached to any hardware. It does not actually change the state of any pins, so it is safe to use without worrying about floating input pins or shorted output pins.
To use with actual hardware, you must use one of the existing machine definition file in the Machines/ subdirectory, or create your own. For example the Grbl_ESP32 Development Board uses the file Machines/3axis_v4.h. If your hardware does not match one of the predefined machines, you can make your own file, perhaps using one of the predefined ones as a starting point. See this wiki page. In Machine.h, #include your file instead of Machines/test_drive.h.
Important: Some shields have revisions levels that use different pins. There are separate machine definition files for the different revisions. Make sure that you use the right one.
Connect the ESP32 to your computer via a USB cable. A serial port choice should appear in Arduino's Tools>Port menu
Select the serial port that corresponds to your ESP32. If more than one serial port is shown, you can work out which one applies by disconnecting your ESP32, then re-opening the Tools dropdown to see which port is no longer in the list. Then reconnect and select the one that reappeared.
Click on the Upload button to begin the compilation/upload process.
The status bar should say "Compiling sketch...", and after some time, the upload process will begin. The window below the status bar shows the result of compilation and the upload progress. You can scroll that window to see the compilation status at the top, like this
Scroll to the bottom to see the final upload result, like this
If the upload does not succeed, like this
either the serial port is no longer connected via the USB cable, or that serial port is already in use, perhaps connected to some other terminal emulator program or GCode sending program. Ensure that it is physically connected, disconnect any other programs that might be using it, and retry the Arduino upload.
For solutions to some other possible upload problems, refer to Other Firmware Upload Errors below.
You may see several warnings during the compile. Most of them come from libraries and should be ignored.
- WARNING: library TMCStepper claims to run on avr architecture(s)
- Multiple libraries were found for "SD.h"
- Multiple libraries were found for "WiFi.h"
- ..and some others
After you have uploaded the firmware, connect to the serial port with the Arduino Serial Monitor at 115200 baud (you can use any terminal emulator or GCode Sender program if you prefer). Press the ESP32 reset button, then you should see a startup message like this
As shown in the highlights, that message contains some useful information including the pin map that was chosen, the current WiFi settings for the web user interface, and the Grbl signon message. Should the firmware crash, the serial output will show information that may be helpful for debugging.
If the serial monitor is open when the firmware runs the first time, you might see an error 7 and possibly other errors. That's normal - Grbl_Esp32 is trying to load saved settings, which don't exist yet, so it loads defaults. You should not see the error again.
You can control the Grbl_Esp32 firmware either from the serial interface - the same as you would with Grbl running an AVR Arduino - or directly over a WiFi connection via the WebUI.
In the serial case, you can use the Arduino Serial Monitor - or any terminal emulator program - to send Grbl and GCode commands that you type directly. That is useful for initial checkout, Grbl configuration, and exploration when you want to keep things simple. For example, you can type "$$" in the command input line at the top of the Arduino Serial Monitor window, then hit the Send button, and Grbl will display a list of its configuration settings. "?" will make Grbl show a status report. You can send simple GCode commands like "G0 X10" to move to specific coordinates, for basic motor testing.
The serial interface can also be used with any "GCode Sender" program, such as those listed here. In this situation, Grbl_Esp32 behaves just like Grbl running on an AVR, except that you might need to reset manually
Instead of using the serial interface and a GCode sender program, you can control Grbl_Esp32 directly over WiFi, using a web browser on any computer on the same network. This is a powerful feature that can lower the overall system cost, improve performance, and eliminate a number of common shortcomings of serial GCode senders. To get started with this WebUI feature, refer to ESP3D Web UI for Grbl_ESP32
It is common on some dev boards to fail to connected and give a message like "Connecting................." The Arduino IDE is having trouble putting the ESP32 in bootloader mode. Try holding down the boot button until it gets past the "Connecting..." phase. Be careful not to touch any of the pins near the button. That could interfere with the flash memory during upload. Adding a 2.2uF to 10uF cap from ESP32 RST to ground can eliminate the problem (no guarantees or support here).
There are also a lot of I/O restrictions regarding the bootloader. See this reference.
You may also see flash errors. Some dev boards have trouble being programmed while attached to a shield. Try removing the dev board from the shield while programming.
After you have programmed the board once with Grbl_ESP32, it is possible to upload new firmware via WiFi. This feature is called OTA - Over The Air - programming. The WebUI...ESP3D tab has a a firmware upload button (yellow cloud). If you put the Arduino IDE compiler into verbose mode, via the the File...Preferences menu, it will display the directory where the compiled (.bin) file is located, so you can select that file for OTA upload.