grbl/PLATFORMIO.md

Building Grbl with PlatformIO

This document explains how to build and upload Grbl using PlatformIO instead of the traditional Makefile approach.

Prerequisites

Install PlatformIO Core or PlatformIO IDE:

• PlatformIO Core (CLI): pip install platformio
• PlatformIO IDE: Install as a VSCode extension or use Atom IDE

Project Structure

The PlatformIO configuration has been set up to work with the existing Grbl source structure:

grbl/
├── platformio.ini          # PlatformIO configuration
├── src/
│   └── main.cpp           # Arduino framework wrapper
├── grbl/                  # Grbl source code (unchanged)
│   ├── *.c, *.h          # Core Grbl files
│   ├── config.h          # Configuration settings
│   ├── cpu_map/          # CPU pin mappings
│   └── defaults/         # Machine defaults
└── Makefile              # Original Makefile (still usable)

Configuration

The platformio.ini file is configured for Arduino Uno (ATmega328P):

[env:uno]
platform = atmelavr
board = uno
framework = arduino

Build Commands

Build the project

pio run

Upload to Arduino

pio run -t upload

Clean build files

pio run -t clean

Resetting GRBL Settings

GRBL stores settings in EEPROM memory, which persists across uploads. When you upload new firmware, your previous settings remain. To reset settings:

Option 1: Reset to Defaults (Recommended after firmware upload)

After uploading, connect via serial monitor and send:

$RST=$

This restores all GRBL settings to the defaults defined in grbl/config.h.

Option 2: Clear EEPROM and Reset

$RST=*

This wipes all EEPROM data including settings and startup blocks.

Option 3: Reset Only Settings (preserve startup blocks)

$RST=#

Verifying Settings

After reset, check your settings with:

$$

Common Workflow After Upload

1. Upload firmware: pio run -t upload
2. Open serial monitor: pio run -t monitor
3. Send reset command: $RST=$
4. Verify settings: $$
5. Unlock if needed: $X

Build Results

The successful build output shows:

• RAM Usage: ~72.5% (1484 bytes / 2048 bytes)
• Flash Usage: ~91.6% (29544 bytes / 32256 bytes)

Compiled firmware is located at .pio/build/uno/firmware.hex

Serial Monitor

To open the serial monitor at 115200 baud (Grbl's default):

pio device monitor -b 115200

Or use PlatformIO's built-in monitor:

pio run -t monitor

Configuration Options

Changing Baud Rate

Edit grbl/config.h:

#define BAUD_RATE 115200  // Default

Machine Defaults

Edit grbl/config.h:

#define DEFAULTS_GENERIC  // Or other machine types

Comparison with Makefile

Both build methods produce equivalent results:

Feature	Makefile	PlatformIO
Compiler	avr-gcc	avr-gcc
Optimization	-Os	-Os
F_CPU	16MHz	16MHz
Baud Rate	115200	115200
Flash Size	~29.5KB	~29.5KB

Troubleshooting

Build Errors

If you encounter build errors, try cleaning the project:

pio run -t clean
pio run

Upload Issues

Ensure the correct serial port is selected. List available ports:

pio device list

Specify port manually:

pio run -t upload --upload-port /dev/ttyUSB0

Dependencies

PlatformIO automatically downloads required toolchains and frameworks. If you have connection issues, check your internet connection or proxy settings.

Notes

• The PlatformIO build uses the Arduino framework which provides setup() and loop() functions
• src/main.cpp wraps Grbl's native main() function to be compatible with Arduino framework
• All original Grbl source files in grbl/ remain unchanged and compatible with the Makefile build
• The build includes all necessary compiler flags to match the original Makefile configuration

Advanced Usage

Custom Build Flags

Add custom flags in platformio.ini:

build_flags = 
    -DCUSTOM_FLAG
    -DANOTHER_OPTION=value

Debugging

PlatformIO supports debugging with compatible hardware:

pio debug