# ESP32-Bit-Pirate Firmware Update Instructions: 3 Methods Explained

> Easily update your ESP32-Bit-Pirate firmware with 3 methods Web Flasher M5Burner or PlatformIO. Discover the fastest browser-based Web Flasher update today.

- Repository: [Geo/ESP32-Bit-Pirate](https://github.com/geo-tp/ESP32-Bit-Pirate)
- Tags: how-to-guide
- Published: 2026-08-02

---

**The ESP32-Bit-Pirate firmware can be updated via Web Flasher (browser-based), M5Burner GUI, or PlatformIO CLI build from source, with the Web Flasher being the quickest option requiring no local toolchain.**

The **ESP32-Bit-Pirate** firmware transforms an ESP32-S3 development board into a versatile multi-protocol analysis tool. This guide covers the complete ESP32-Bit-Pirate firmware update process, including architecture details from the `pioarduino` branch source code and step-by-step instructions for each flashing method.

---

## Firmware Architecture Overview

Understanding the firmware structure helps troubleshoot update issues and explains why the binary works across multiple board variants.

### Core Components

| Layer | Key Classes | Source Location |
|-------|-------------|---------------|
| **Board detection** | `StickS3Board`, `CardputerBoard`, `TEmbedBoard`, `WaveShareS3GeekBoard`, `CustomBoard` | [[`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/main.cpp) |
| **Display output** | `SerialTerminalView`, `WebTerminalView`, `CardputerTerminalView` | [[`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/main.cpp) |
| **Input handling** | `SerialTerminalInput`, `WebTerminalInput`, `DefaultInput` | [[`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/main.cpp) |
| **Configuration** | `BootModeConfigurator`, `TerminalTypeConfigurator`, `WifiTypeConfigurator` | [`src/Configurators/`](https://github.com/geo-tp/ESP32-Bit-Pirate/tree/pioarduino/src/Configurators) |
| **Dependency injection** | `DependencyProvider` | [[`src/Providers/DependencyProvider.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Providers/DependencyProvider.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/Providers/DependencyProvider.cpp) |
| **Event loop** | `ActionDispatcher` | [[`src/Dispatchers/ActionDispatcher.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Dispatchers/ActionDispatcher.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/Dispatchers/ActionDispatcher.cpp) |

### Boot Sequence

When firmware boots after a successful ESP32-Bit-Pirate firmware update, the system executes this initialization flow:

1. Board object instantiated via `#if defined(DEVICE_…)` preprocessor blocks
2. `BootModeConfigurator` reads NVS for forced boot modes (e.g., USB-Adapter mode)
3. `TerminalTypeConfigurator` presents UI selector for **Serial**, **Wi-Fi**, or **Standalone** mode
4. `WifiTypeConfigurator` collects credentials if Wi-Fi mode selected
5. `DependencyProvider` constructs the full object graph
6. `ActionDispatcher` enters infinite event-processing loop

This modular architecture, implemented in the `pioarduino` branch, enables a single firmware binary to adapt to diverse ESP32-S3 boards at runtime.

---

## Method 1: Web Flasher (Recommended)

The **Web Flasher** provides the fastest ESP32-Bit-Pirate firmware update path with zero local dependencies.

### Prerequisites

- Chrome, Edge, or Opera browser (WebUSB support required)
- USB cable connected to ESP32-S3 board
- Binary file from [GitHub Releases](https://github.com/geo-tp/ESP32-Bit-Pirate/releases)

### Step-by-Step Instructions

Navigate to the flasher URL:

```bash
https://geo-tp.github.io/ESP32-Bit-Pirate/webflasher/

```

1. Connect your ESP32-S3 board via USB
2. Click **"Select Firmware"** and choose `bit-pirate-*.bin` from release assets
3. Select the correct serial port when prompted
4. Press **"Flash"** and wait for verification

The Web Flasher streams the binary directly via WebSerial protocol—no Python, PlatformIO, or drivers required beyond standard USB CDC support.

---

## Method 2: M5Burner (M5Stack Devices)

For **M5Stack hardware** (Stick-S3, Atom-S3, Stamp-S3, Cardputer), M5Burner provides a GUI alternative for ESP32-Bit-Pirate firmware updates.

### When to Use M5Burner

- Device shipped with M5Burner pre-installed
- Preference for graphical interface over browser tools
- Need M5-specific partition schemes or initialization

### Process Overview

1. Launch M5Burner application
2. Navigate to device category (Stick-S3 / Atom-S3 / Stamp-S3 / Cardputer)
3. Locate **Bit-Pirate** firmware in the app list
4. Select serial port and click **Burn**

M5Burner automatically handles erase, flash, and verification cycles using the same underlying [`esptool.py`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/esptool.py) protocol as other methods.

---

## Method 3: PlatformIO CLI (From Source)

Use **PlatformIO CLI** for custom modifications, development builds, or unsupported board variants requiring ESP32-Bit-Pirate firmware updates with specific configurations.

### Build Environment Setup

```bash

# Clone the pioarduino branch

git clone -b pioarduino https://github.com/geo-tp/ESP32-Bit-Pirate.git
cd ESP32-Bit-Pirate

# Install dependencies and build

platformio run

```

### Flash Compiled Binary

```bash

# Automatic upload to detected port

platformio run --target upload

# Specify port explicitly if needed

platformio run --target upload --upload-port /dev/ttyUSB0

```

### Output Location

Post-build binaries reside at:

```bash
pioarduino/.pio/build/[environment]/firmware.bin

```

The [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini) file defines multiple environments for different board variants—verify your `DEVICE_*` build flag matches target hardware:

```ini
[env:stick-s3]
build_flags = 
    -D DEVICE_STICK_S3

[env:cardputer]
build_flags = 
    -D DEVICE_CARDPUTER

```

---

## Post-Update Verification

After completing any ESP32-Bit-Pirate firmware update method, verify installation via serial console:

### Linux/macOS Connection

```bash
screen /dev/ttyUSB0 115200

```

### Windows Connection (PowerShell)

```powershell
Get-Content \\.\COM3 -Raw -Wait -Encoding ascii

```

### Verification Commands

```text
> version
ESP32-Bit-Pirate v2.x.x

> mode
HiZ

> scan
Scanning I2C bus … found devices: 0x3C 0x5A

```

Successful response confirms proper flash and boot sequence execution through `ActionDispatcher`.

---

## Wi-Fi Mode Activation (Optional)

For wireless operation post-update:

```text
> terminal wifi-client
Enter SSID: MyWiFi
Enter Password: ********
Connecting… IP = 192.168.1.42

```

The `TerminalTypeConfigurator` writes settings to NVS; subsequent boots auto-connect. Access the web CLI at the displayed IP address—the `WebTerminalView` and `WebTerminalInput` classes in [[`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/main.cpp) provide identical command functionality over HTTP.

---

## Key Source Files for Troubleshooting

| File | Diagnostic Value |
|------|----------------|
| [[`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/main.cpp) | Boot failures, board detection issues |
| [[`src/Configurators/TerminalTypeConfigurator.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Configurators/TerminalTypeConfigurator.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/Configurators/TerminalTypeConfigurator.cpp) | Mode selection UI problems |
| [[`src/Providers/DependencyProvider.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Providers/DependencyProvider.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/Providers/DependencyProvider.cpp) | Dependency injection errors |
| [[`src/Dispatchers/ActionDispatcher.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Dispatchers/ActionDispatcher.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/Dispatchers/ActionDispatcher.cpp) | Command routing failures |
| [[`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/platformio.ini) | Build configuration, board definitions |

---

## Summary

- **Web Flasher** — Fastest ESP32-Bit-Pirate firmware update method; browser-only, no toolchain
- **M5Burner** — Optimal for M5Stack device ecosystem with GUI preference
- **PlatformIO CLI** — Required for source modifications and custom board support
- **Post-update verification** — Serial connection at 115200 baud with `version`, `mode`, `scan` commands
- **Architecture resilience** — `DependencyProvider` and `ActionDispatcher` enable single binary across multiple ESP32-S3 boards

---

## Frequently Asked Questions

### Does ESP32-Bit-Pirate firmware update require erasing flash first?

No automatic erase is required for Web Flasher or M5Burner methods—these tools handle flash layout automatically. For PlatformIO CLI, add `--target erase` before upload if experiencing corruption: `platformio run --target erase --target upload`.

### Can I update firmware over Wi-Fi after initial flash?

No, the ESP32-Bit-Pirate firmware does not implement over-the-air (OTA) updates in the `pioarduino` branch. OTA capability would require extending `WifiService` in [[`src/Services/WifiService.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Services/WifiService.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/tree/pioarduino/src/Services) with partition writing logic.

### Why does my board show garbled output after updating?

Baud rate mismatch or incorrect board definition in [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini). Verify `DEVICE_*` flag matches your hardware in [[`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/pioarduino/src/main.cpp) lines 25-45, and connect at **115200 baud**.

### Where are Wi-Fi credentials stored after `terminal wifi-client` configuration?

In ESP32 **NVS (Non-Volatile Storage)** partition. The `TerminalTypeConfigurator` and `WifiTypeConfigurator` classes in [`src/Configurators/`](https://github.com/geo-tp/ESP32-Bit-Pirate/tree/pioarduino/src/Configurators) handle persistence—credentials survive firmware updates but not full flash erases.