baebeb436f
- Added changelog section documenting all modifications since forking - Documented December 4, 2025 changes (inverted servo PWM, M5 fix) - Listed earlier modifications (servo mode, homing fix)
182 lines
4.3 KiB
Markdown
182 lines
4.3 KiB
Markdown
# 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
|
|
```
|