Building Firmware from Source

For Developers

This page is for developers who want to build eSpa firmware from source, customize the code, or contribute to the project. If you just want to update your eSpa device to the latest version, see the Firmware Updating guide instead.

The eSpa firmware is open source and available on GitHub. It's built using Platform.io, a powerful development environment for embedded systems that makes building and flashing firmware straightforward.

This guide covers how to set up your development environment and build the firmware using either the Platform.io GUI (in VSCode) or the command-line interface.

Prerequisites

Before you begin, make sure you have:

A computer running Windows, macOS, or Linux
A USB cable to connect your eSpa device
Git installed on your system
Python 3.6 or newer

Setting Up Platform.io GUI (VSCode)

The Platform.io IDE extension for Visual Studio Code provides a visual interface for building and flashing firmware.

Installation

Install VSCode: Download and install Visual Studio Code if you don't already have it
Install Platform.io Extension:
- Open VSCode
- Click the Extensions icon in the left sidebar (or press Ctrl+Shift+X / Cmd+Shift+X)
- Search for "PlatformIO IDE"
- Click "Install"
- Wait for the installation to complete (this may take a few minutes)
- Restart VSCode when prompted

Getting the Source Code

Clone the eSpa repository to your local machine:

bash

git clone https://github.com/wayne-love/ESPySpa.git
cd ESPySpa

Alternatively, you can download the repository as a ZIP file from GitHub and extract it.

Opening the Project

In VSCode, click File > Open Folder (or File > Open on macOS)
Navigate to the ESPySpa directory you cloned/extracted
Click "Select Folder" to open the project
Platform.io will automatically detect the project and initialize it (this may take a moment)

Understanding Build Environments

The eSpa project supports multiple hardware configurations through Platform.io environments. Open the platformio.ini file at the root of the project to see all available environments:

esp32dev: For generic ESP32 development boards and DIY builds
espa-v1: For eSpa Mini and eSpa Max v1.x PCBs (ESP32-S3 based)
espa-v2: For eSpa Mini and eSpa Max v2.x PCBs (newer hardware)

Each environment has specific settings for the target hardware, including pin configurations, board definitions, and build flags.

TIP

Not sure which environment to use? Check the hardware section for details about your device.

Building the Firmware

Select your environment:
- Look at the bottom toolbar in VSCode
- Click on "Default (ESPySpa)" or the current environment name
- Select your target environment from the list (e.g., espa-v1, espa-v2, or esp32dev)
Build the project:
- Click the checkmark (✓) icon in the bottom toolbar, or
- Press Ctrl+Alt+B / Cmd+Alt+B, or
- Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run "PlatformIO: Build"
Watch the build progress:
- The terminal will open and show build output
- First build will take several minutes as dependencies are downloaded
- Subsequent builds are much faster (typically 10-30 seconds)
- Look for "SUCCESS" message when complete

TIP

The first build downloads all necessary libraries and toolchains. This is a one-time process and can take 5-10 minutes depending on your internet connection.

Uploading to Your Device

Connect your device:
- Connect your eSpa to your computer via USB-C cable
- Make sure the cable supports data transfer (not just power)
Upload firmware:
- Click the right arrow (→) icon in the bottom toolbar, or
- Press Ctrl+Alt+U / Cmd+Alt+U, or
- Open Command Palette and run "PlatformIO: Upload"
Monitor the upload:
- Platform.io will automatically build (if needed) and then upload
- You'll see progress in the terminal
- Upload typically takes 1-2 minutes

Monitoring Serial Output

To see debug output from your eSpa:

Start serial monitor:
- Click the plug icon (🔌) in the bottom toolbar, or
- Press Ctrl+Alt+S / Cmd+Alt+S, or
- Open Command Palette and run "PlatformIO: Serial Monitor"
Upload and monitor in one step:
- Click the right arrow with line (→|) icon in the bottom toolbar
- This builds, uploads, and starts monitoring automatically
Using the monitor:
- Type v and press Enter to enable verbose logging
- Type h and press Enter to see available commands
- Press Ctrl+C to stop monitoring

TIP

Keep the serial monitor open while developing to see real-time debug output and catch errors immediately.

Setting Up Platform.io CLI

If you prefer working from the command line, Platform.io offers a powerful CLI that provides the same functionality as the GUI.

Installation

bash

# Install Platform.io Core (CLI) using pip
pip install -U platformio

# Verify installation
pio --version

TIP

If you already have the Platform.io VSCode extension installed, you can use the CLI through VSCode's integrated terminal - the pio command will be available automatically.

Getting the Source Code

bash

# Clone the repository
git clone https://github.com/wayne-love/ESPySpa.git
cd ESPySpa

# View available environments
pio project config

Building with CLI

bash

# Build for specific environment
pio run -e espa-v1

# Build for multiple environments
pio run -e espa-v1 -e espa-v2

# Build all environments (defined in platformio.ini)
pio run

# Clean build artifacts before building
pio run --target clean
pio run -e espa-v1

The build output will show compilation progress and any errors. Compiled firmware will be in .pio/build/<environment>/ directory.

Uploading with CLI

bash

# Upload to connected device
pio run -e espa-v1 --target upload

# Build and upload in one command
pio run -e espa-v1 --target upload

# Upload to specific port
pio run -e espa-v1 --target upload --upload-port /dev/ttyUSB0

Monitoring Serial Output

bash

# Start serial monitor
pio device monitor

# Specify baud rate
pio device monitor --baud 115200

# Monitor specific port
pio device monitor --port /dev/ttyUSB0

# Upload and immediately start monitoring
pio run -e espa-v1 --target upload --target monitor

TIP

In the serial monitor, type v + Enter for verbose logging, or h + Enter to see available commands. Press Ctrl+C to exit the monitor.

Useful CLI Commands

bash

# List all connected devices and their ports
pio device list

# Update Platform.io and all packages
pio upgrade
pio pkg update

# Check code for issues (static analysis)
pio check

# Clean all build artifacts
pio run --target clean

# Show project configuration
pio project config

# Install specific library
pio pkg install -e espa-v1 "ArduinoJson@^6.21.0"

Development Workflow Tips

Making Code Changes

Edit source files: Modify files in the src/ directory
Build to check for errors: Run a build to catch compilation errors early
Upload and test: Flash to your device and monitor serial output
Iterate: Make changes, rebuild, and test until complete

Working with Multiple Devices

If you have multiple ESP32 devices connected:

bash

# List all devices to find port names
pio device list

# Upload to specific device
pio run -e espa-v1 --target upload --upload-port COM3

Or specify the port in platformio.ini:

ini

[env:espa-v1]
upload_port = /dev/ttyUSB0  ; Linux/Mac
; upload_port = COM3         ; Windows

Creating Custom Environments

You can create custom build environments in platformio.ini:

ini

[env:my-custom-build]
extends = env:espa-v1
build_flags = 
    ${env:espa-v1.build_flags}
    -DMY_CUSTOM_FLAG=1
    -DDEBUG_MODE

Testing Development Branches

To test unreleased features:

bash

# Switch to development branch
git checkout develop

# Pull latest changes
git pull origin develop

# Rebuild with new code
pio run --target clean
pio run -e espa-v1 --target upload

WARNING

Development branches may contain unstable code. Always be prepared to flash stable firmware if issues occur.

Troubleshooting Platform.io Issues

Device Not Recognized

If Platform.io can't find your device:

Check USB drivers: Install drivers for your ESP32 board
- CH340 drivers - Common on cheaper boards
- CP2102 drivers - Common on official boards
Verify cable: Use a data-capable USB cable (not power-only)
List devices: Run pio device list to see all connected serial devices

Check permissions (Linux/Mac): Add your user to the dialout group:

bash

sudo usermod -a -G dialout $USER
# Log out and back in for changes to take effect

Upload Failed - "Timed Out Waiting for Packet Header"

This common error means the ESP32 isn't entering flash mode:

Hold BOOT button: Press and hold the BOOT button on your board, start the upload, release when upload begins
Auto-reset issues: Some boards need manual reset - press BOOT + RST, release RST, release BOOT
Lower upload speed: Add to your environment in platformio.ini:
ini
```
upload_speed = 115200
```
Try different port: Some USB ports provide better power/signal than others

Build Errors

If compilation fails:

Clean and rebuild:

bash

pio run --target clean
pio run -e espa-v1

Update dependencies:
bash
```
pio pkg update
pio pkg install
```
Delete cache:
bash
```
rm -rf .pio
pio run -e espa-v1
```
Check Python version: Ensure Python 3.6+ is installed:
bash
```
python --version
```

Wrong Environment Selected

If firmware builds but device doesn't work:

Verify environment: Make sure you're building for the correct hardware
- eSpa v1 PCBs → espa-v1
- eSpa v2 PCBs → espa-v2
- DIY/generic boards → esp32dev
Check board in platformio.ini: Ensure the board setting matches your hardware

Erase flash and re-upload:

bash

pio run --target erase
pio run -e espa-v1 --target upload

Serial Monitor Not Working

If you can't see serial output:

Check baud rate: eSpa uses 115200 baud (default for Platform.io)
Close other programs: Only one program can access the serial port at a time
Specify port explicitly:
bash
```
pio device monitor --port /dev/ttyUSB0
```

Try after upload:

bash

pio run -e espa-v1 --target upload --target monitor

Permission Denied (Linux/Mac)

If you get "Permission denied" errors:

Linux:

bash

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Or temporarily fix permissions
sudo chmod 666 /dev/ttyUSB0

Mac:

bash

# Check permissions
ls -l /dev/cu.usb*

# If needed, may require running with elevated permissions
sudo pio run -e espa-v1 --target upload

Out of Memory During Build

If compilation runs out of memory:

Close other applications: Free up system RAM
Build one environment at a time:
bash
```
pio run -e espa-v1
```
Increase system swap (Linux)

Platform.io Stuck or Frozen

If Platform.io becomes unresponsive:

Kill Platform.io processes:

bash

# Linux/Mac
pkill -f platformio

# Windows (Task Manager)
# End "Python" processes related to Platform.io

Restart VSCode if using the GUI
Clear Platform.io cache:
bash
```
rm -rf ~/.platformio/.cache
```

Dependencies Won't Update

If libraries aren't updating properly:

bash

# Force clean and reinstall
rm -rf .pio
pio pkg install --force

# Update Platform.io itself
pio upgrade

# Update all libraries
pio pkg update

Getting Help

If you're still experiencing issues:

Check Discord: Search the #development channel for similar issues
Platform.io docs: Visit Platform.io documentation
Ask for help: Post in Discord #development with:
- Your operating system
- Platform.io version (pio --version)
- Environment you're building (espa-v1, etc.)
- Full error message from the terminal
- Output of pio device list

Contributing to eSpa

Interested in contributing to the project? Here's how:

Fork the repository on GitHub
Create a feature branch: git checkout -b my-feature
Make your changes and test thoroughly
Commit with clear messages: git commit -m "Add feature X"
Push to your fork: git push origin my-feature
Open a Pull Request on GitHub

See the contribution guidelines for more details.

TIP

Join the eSpa Discord #development channel to discuss ideas and get feedback before starting major changes.

Building Firmware from Source ​

Prerequisites ​

Setting Up Platform.io GUI (VSCode) ​

Installation ​

Installation ​

Getting the Source Code ​

Opening the Project ​

Understanding Build Environments ​

Building the Firmware ​

Uploading to Your Device ​

Monitoring Serial Output ​

Setting Up Platform.io CLI ​

Installation ​

Getting the Source Code ​

Building with CLI ​

Uploading with CLI ​

Monitoring Serial Output ​

Useful CLI Commands ​

Development Workflow Tips ​

Making Code Changes ​

Working with Multiple Devices ​

Creating Custom Environments ​

Testing Development Branches ​

Troubleshooting Platform.io Issues ​

Device Not Recognized ​

Upload Failed - "Timed Out Waiting for Packet Header" ​

Build Errors ​

Wrong Environment Selected ​

Serial Monitor Not Working ​

Permission Denied (Linux/Mac) ​

Out of Memory During Build ​

Platform.io Stuck or Frozen ​

Dependencies Won't Update ​

Getting Help ​

Contributing to eSpa ​

Building Firmware from Source

Prerequisites

Setting Up Platform.io GUI (VSCode)

Installation

Installation

Getting the Source Code

Opening the Project

Understanding Build Environments

Building the Firmware

Uploading to Your Device

Monitoring Serial Output

Setting Up Platform.io CLI

Installation

Getting the Source Code

Building with CLI

Uploading with CLI

Monitoring Serial Output

Useful CLI Commands

Development Workflow Tips

Making Code Changes

Working with Multiple Devices

Creating Custom Environments

Testing Development Branches

Troubleshooting Platform.io Issues

Device Not Recognized

Upload Failed - "Timed Out Waiting for Packet Header"

Build Errors

Wrong Environment Selected

Serial Monitor Not Working

Permission Denied (Linux/Mac)

Out of Memory During Build

Platform.io Stuck or Frozen

Dependencies Won't Update

Getting Help

Contributing to eSpa