# Flash p3a Firmware

Flash the p3a firmware to your Waveshare ESP32-P4 board. This is a one-time process — after the initial flash, all future updates are installed wirelessly via `http://p3a.local/ota`.

> **Just got your board?** This page is the deep-dive on flashing methods. If you'd rather follow a single end-to-end walkthrough that covers flashing, Wi-Fi setup, and seeing your first artwork, start with the [Quick Start Guide](QUICK-START.md).

---

## Option 1: Web Flasher — Recommended

The easiest way to flash your p3a. No software installation required — just a web browser.

**Requirements:** Chrome 89+ or Edge 89+ (Firefox and Safari don't support WebSerial)

1. Go to the [**p3a Web Flasher**](https://fabkury.github.io/p3a/web-flasher/)
2. Select the firmware version from the dropdown
3. Connect your p3a via USB-C
4. Click **Connect** and select your device from the browser prompt
5. Click **Flash Device**
6. Wait ~2 minutes
7. Done! Your device will automatically reboot into p3a.

The web flasher downloads firmware directly from GitHub and flashes it to your device — works on Windows, macOS, and Linux.

---

## Option 2: p3a Flasher (Windows)

A standalone Windows application for flashing — useful if you don't have Chrome/Edge or prefer an offline tool.

1. Download `p3a-flasher.exe` from the [latest GitHub Release](https://github.com/fabkury/p3a/releases/latest)
2. Connect your p3a via USB-C
3. Run `p3a-flasher.exe`
4. Click **Flash Device**
5. Wait ~2 minutes
6. Done! Your device will automatically reboot into p3a.

The flasher auto-detects your device and includes the firmware — no installation, configuration or Internet connection needed.

---

## Option 3: Command Line (All Platforms)

For macOS, Linux, or if you prefer the command line. This method gives you full control over the flashing process.

### Step 1: Install Python and esptool

**Windows:**
1. Download Python from [python.org](https://www.python.org/downloads/)
2. During installation, check **"Add Python to PATH"**
3. Open PowerShell and run:
   ```powershell
   pip install esptool
   ```

**macOS:**
```bash
brew install python
pip3 install esptool
```

**Linux:**
```bash
sudo apt install python3 python3-pip
pip3 install esptool
```

### Step 2: Download firmware

1. Go to [github.com/fabkury/p3a/releases](https://github.com/fabkury/p3a/releases)
2. Download the firmware `.zip` file from the latest release
3. Extract to a folder (e.g., `p3a-firmware`)

### Step 3: Connect the board

1. Use a **USB-C data cable** (charging-only cables won't work)
2. Connect to the **UART (flashing/serial) USB-C port** on your board — labelled UART/Serial on the silkscreen, not the HS port used for USB storage
3. Find your serial port:
   - **Windows:** Open Device Manager → Ports → Note the COM number (e.g., `COM5`)
   - **macOS:** Run `ls /dev/cu.usb*` in Terminal
   - **Linux:** Run `ls /dev/ttyUSB*` or `ls /dev/ttyACM*`

### Step 4: Flash

Open a terminal in the firmware folder and run one command:

**Windows PowerShell:** (replace `COM5` with your port)
```powershell
python -m esptool --chip esp32p4 -p COM5 -b 460800 --before default_reset --after hard_reset write_flash --flash-mode dio --flash-freq 80m --flash-size 32MB --force "@flash_args"
```

**Windows Command Prompt:**
```cmd
python -m esptool --chip esp32p4 -p COM5 -b 460800 --before default_reset --after hard_reset write_flash --flash-mode dio --flash-freq 80m --flash-size 32MB --force @flash_args
```

**macOS/Linux:** (replace `/dev/ttyUSB0` with your port)
```bash
python3 -m esptool --chip esp32p4 -p /dev/ttyUSB0 -b 460800 --before default_reset --after hard_reset write_flash --flash-mode dio --flash-freq 80m --flash-size 32MB --force @flash_args
```

Wait ~2 minutes for flashing to complete.

### Step 5: Done!

The device will automatically reboot into p3a:
1. The p3a splash screen appears
2. Connect to the `p3a-setup` Wi-Fi network to configure your Wi-Fi
3. Access your p3a at `http://p3a.local/`

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "No serial port found" | Try a different USB cable — many are charge-only |
| "Failed to connect" | Hold the **BOOT** button (the top one, farther from the USB-C ports) while connecting |
| Permission denied (Linux) | Run: `sudo usermod -a -G dialout $USER` then log out/in |
| Wrong COM port (Windows) | Check Device Manager → Ports |
| Timeout errors | Try `-b 115200` instead of `-b 460800` |

---

## After flashing

### Wireless updates (OTA)

After the initial flash, update wirelessly:
1. Open `http://p3a.local/ota` in your browser
2. Click "Check for Updates"
3. Click "Install Update" if an update is available

### Adding artwork

Copy WebP, GIF, PNG/APNG, JPEG, or BMP files to a `p3a/animations/` folder on a microSD card (i.e. create a `p3a` folder at the root of the card, and an `animations` folder inside it), then insert it into your p3a.

See [HOW-TO-USE.md](HOW-TO-USE.md) for detailed instructions.

---

## Advanced: Build from source

For developers who want to customize the firmware:

```bash
# Clone and build
git clone https://github.com/fabkury/p3a.git
cd p3a
idf.py set-target esp32p4
idf.py build
```

The build automatically creates:
- `release/v{VERSION}/` — Firmware files for distribution

On Windows, you can additionally build the standalone `p3a-flasher.exe` (with embedded firmware) by passing `-DP3A_BUILD_FLASHER=ON`:
```bash
idf.py build -DP3A_BUILD_FLASHER=ON
```

Requires [ESP-IDF v5.5.x](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/).