# 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`](platformio.ini:1) file is configured for Arduino Uno (ATmega328P):

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

## Build Commands

### Build the project
```bash
pio run
```

### Upload to Arduino
```bash
pio run -t upload
```

### Clean build files
```bash
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`](grbl/config.h:1).

### 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):
```bash
pio device monitor -b 115200
```

Or use PlatformIO's built-in monitor:
```bash
pio run -t monitor
```

## Configuration Options

### Changing Baud Rate
Edit [`grbl/config.h`](grbl/config.h:37):
```c
#define BAUD_RATE 115200  // Default
```

### Machine Defaults
Edit [`grbl/config.h`](grbl/config.h:34):
```c
#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:
```bash
pio run -t clean
pio run
```

### Upload Issues
Ensure the correct serial port is selected. List available ports:
```bash
pio device list
```

Specify port manually:
```bash
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`](src/main.cpp:1) wraps Grbl's native [`main()`](grbl/main.c:29) function to be compatible with Arduino framework
- All original Grbl source files in [`grbl/`](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`](platformio.ini:1):
```ini
build_flags = 
    -DCUSTOM_FLAG
    -DANOTHER_OPTION=value
```

### Debugging
PlatformIO supports debugging with compatible hardware:
```bash
pio debug
```