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

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/pioarduino/src/main.cpp)
Display output	SerialTerminalView, WebTerminalView, CardputerTerminalView	[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/pioarduino/src/main.cpp)
Configuration	BootModeConfigurator, TerminalTypeConfigurator, WifiTypeConfigurator	src/Configurators/
Dependency injection	DependencyProvider	[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/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

Step-by-Step Instructions

Navigate to the flasher URL:

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 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

# 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

# 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:

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

The platformio.ini file defines multiple environments for different board variants—verify your DEVICE_* build flag matches target hardware:

[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

screen /dev/ttyUSB0 115200

Windows Connection (PowerShell)

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

Verification Commands

> 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:

> 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/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/pioarduino/src/main.cpp)	Boot failures, board detection issues
[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/pioarduino/src/Providers/DependencyProvider.cpp)	Dependency injection errors
[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/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/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. Verify DEVICE_* flag matches your hardware in [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/ handle persistence—credentials survive firmware updates but not full flash erases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}