Compiling with PlatformIO - bdring/Grbl_Esp32 GitHub Wiki

Intro

This page explains how to compile Grbl_Esp32 with PlatformIO and VSCode.

Your starting point

  • Mandatory

    • Some experience in C++ programming
    • Basic CNC know how
    • ESP32 DevKit board with USB cable

  • Optional

    • A complete hardware like Bart´s Tindie board
    • A working CNC machine (incl. motor driver, steppers, buttons, etc.)

PlatformIO vs. Arduino IDE

Arduino IDE is an easy-to-use "Integrated Development Environment" (IDE) for microcontroller software development. IDE means that code editing, program compilation, downloading the compiled code to a microprocessor, and testing can all be done in one environment. It was originally intended for Arduino hardware but now has been adapted to many different microcontrollers including ESP32. It is stable, well documented, and very easy to use for small projects. For larger projects, its simplicity can become limiting.

Grbl_Esp32 is a relatively large project that pushes the limits of Arduino IDE. One primary annoyance is that, if you change anything, Arduino IDE recompiles all the code, even parts that did not change. The time that takes impedes development, where you often need to make a series of small changes and test them rapidly. Furthermore, Arduino IDE does not have good support for professional code management practices like version control, code review, cooperation among multiple programmers, and issue tracking.

To overcome these limitations, the Grbl_Esp32 core developers instead use the PlatformIO microcontroller compilation system, coupled with the Visual Studio Code (VSCode) editing system. PlatformIO handles the details of setting up the microcontroller's compiler, development framewors, libraries and board configurations, loading code onto the microcontroller, and testing. VSCode has extensive tools for editing and managing source code, with point-and-click integration to PlatformIO and source code management systems like git and GitHub. The combination of PlatformIO and VSCode provides an alternate to Arduino IDE that is much faster (after the initial setup) and much more capable.

(PlatformIO also works well with other editing systems like Atom, Sublime Text, EMACS, Visual Studio, and vi. If you prefer one of those other editors, search the web for instructions about using PlatformIO with your editor. For simplicity, this document describes only the VSCode case.)

VSCode has many extensions for handling common programming situations. In addition to the PlatformIO extension, this document suggests a few others that are particularly convenient for use with Grbl_Esp32.

Let´s take a walk through a fresh installation and finally upload Grbl_Esp32 onto the ESP32 for first testing.

Installation of VSCode & PlatformIO

1. Git

The Grbl_ESP32 project uses the Git version control systems to track changes to the code, in conjunction with the GitHub web service for storing code in the cloud. Using git is not strictly necessary - you could just download a .zip file with a given version of the source code - but git has many advantages. You can easily track different versions of the code, switch back and forth between released and experimental code, send proposed changes back to the core developers, etc.

If you already have git on your machine, VSCode will use the existing installation. If not, first install git . More information about Git can be found at Git documentation.

2. VSCode

Install Visual Studio Code by following the documentation. A fresh installation of VSCode, here in Windows, looks like this.

3. PlatformIO extension

Open the VSCode extensions tab by clicking the "gear" icon at the bottom left corner and choosing Extensions. In the "Search Extension in Marketplace" box at the top, type "platformio", choose the "PlatformIO IDE" extension, then install it with the blue "Install" button.

4. GitLens extension (optional)

The GitLens extension offers code comparison and the whole functionality of git for VSCode. This is particularly useful for developers who need to look in detail at how the code has changed over time. Search for "GitLens" in the Extensions manager, as above, and install it. See picture below.

5. C/C++ extension

Most of the Grbl_Esp32 source code is written in C/C++. There are various different extensions to help with C/C++ development - highlighting keywords, on-the-fly error checking, showing function arguments, etc. The C/C++ extension from Microsoft works well. See picture below.

6. Final overview of installed extensions

At this point, the installation is finished. The next step is project setup.

Importing Grbl_Esp32 into VSCode/PlatformIO

The Grbl_Esp32 source code contains a "platformio.ini" file that tells PlatformIO how to compile it.

If you already have the Grbl_Esp32 source code on your computer, just go to File>Open Folder from the top menu bar, and select the folder with Grbl_Esp32. The presence of "platformio.ini" in that folder will activate the PlatformIO extension.

If you do not already have the source code, you can get it directly from within VSCode. In the VSCode sidebar, click on the "alien" icon for PlatformIO to bring up the "PLATFORMIO: QUICK ACCESS" panel, then select Clone Git Project.

At the top, you will then see a box that says "Provide repository URL or pick a repository source". Paste https://github.com/bdring/Grbl_Esp32 in that box and click on the Clone from URL ... line that appears below it.

That will bring up a file selector dialog where you can choose the directory that will contain the new "Grbl_Esp32" subdirectory. Then you will see

then

Click Open and VSCode will connect to the Grbl_Esp32 source code.

Customize "Grbl_Esp32/src/Machine.h"

Each CNC machine requires some specific machine setup. Grbl_ESP32 defaults to a do-nothing "test_drive.h" machine definition. You will eventually need to setup a real machine definition file.

The file Grbl_Esp32/src/Machine.h contains the line #include "src/Machines/test_drive.h". It selects the "test_drive" machine - 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 Grbl_Esp32/src/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.

You can use VSCode to edit the file as shown

How to compile Grbl_Esp32 (USB, over the air, Web UI)

The VSCode PlatformIO extension adds some icons to the status bar at the bottom of the window

You can hover the mouse over an icon to verify what it does.

The "check mark" icon compiles ("builds") the firmware from source but does not upload it to the ESP32 module. The compilation process, with any resulting errors, is shown in a VSCode "TERMINAL" pane.

The "right arrow" icon compiles and then, if successful, uploads to the ESP32 module. This is the one that you will use most frequently.

The "trash can" icon perform a "clean" step. In most cases, PlatformIO can detect when a source file has changed, and will only recompile the changed files, thus speeding up the process for subsequent recompiles after you make small changes. In a few situations - particularly when you make changes in the Custom/ folder - the change detection does not work, so you have to force PlatformIO to recompile everything. That is what "clean" is for - it discards all of the previous compilation results so the compilation process starts from a clean slate and compiles everything.

The "power plug" icon starts a serial monitor that connects to the ESP32 serial port, so you can interact with Grbl_Esp32 serially.

The normal process is "Upload" (which does the compile step automatically), then "Serial Monitor".

Possible Problems

  • If you have an existing PlatformIO installation from earlier work you have done, there is a chance that the old installation might interfere with the new work. PlatformIO stores a lot of tools in the directory UserHomeDirectory/.platformio . (On Windows, UserHomeDirectory is usually "C:/Users/YourUserName"). Old versions of those tools might not work properly. In that case, you can try deleting or renaming that old .platformio directory. Then you will have to use VSCode's Extension Manager to Uninstall then (re) Install the PlatformIO extension. You might be prompted to reload VSCode a couple of times; ask the internet for how to do that.

Upload via USB

Now connect your ESP32 board via USB to your PC. Remember, this basic procedure is related to the chip, not the board. In other words, you could take

  • Espressif DevKit board
  • Bart´s Grbl_ESP32 CNC Development Board V4.1
  • Your own board

Hints

  • some ESP32 boards require to press the EN button to initiate programming. This could be compensated by adding a capacitor
  • PlatformIO recognizes the USB connection to your ESP32 board automatically. In case of issues, refer to upload options

Upload via OTA (over the air)

This step doesn´t work with a factory fresh ESP32 chip. After first flashing with Grbl_Esp32 this is a quite useful feature, because the machine could be flashed without physical access to the hardware.

Prerequisites

  • Grbl_Esp32 flashed for the first time
  • OTA enabled in Grbl_Esp32
  • Router, security, ... set up
  • Antenna connected, where applicable
  • Grbl_Esp32 Web UI accessible via WIFI
  • Take a test ride with manual firmware upload via Web UI to be sure it worked once

Having said this, add these lines to your platformio.ini file in the main folder

[env]
upload_protocol = espota
upload_port = 192.168.xx.xx

The upload_port is the IP address of your machine.

Click PlatformIO::Upload button in the blue ribbon

Uploading: [============================================================] 99%
Uploading: [============================================================] 99%
Uploading: [============================================================] 100% Done...


13:31:35 [INFO]: Waiting for result...
13:31:36 [INFO]: Result: OK
13:31:36 [INFO]: Success

Upload via ESP32 Web UI

Once the ESP32 Web UI is working, you can also upload the generated firmware.bin file via Web UI.

Hints

  • Potentially adjust your PCs firewall to allow incoming traffic (issue)
  • Test the ESP32 connectivity. The expected result, e.g. by connecting via USB cooenction looks like this
  • Could be helpful to archive a well working firmware.bin file, together with a working repository, as a backup. Just in case s.th. is getting weird and you need get back to a recently defined starting point

Where to go from here

Common FAQ

  • the main branch is the stable environment, which you´ll see when opening the GitHub website. There are other branches like devt or ones to try specific features.

Unsorted wiki enhancements, depending on user interest

  • Update Grbl_Esp32
  • Update ESP32 firmware (current version AT 2.1)
  • Fork Grbl_Esp32 and maintain own programming with GitHub
  • Simple program, e.g. small user defined function (header, .c file)