# ESP32-Bit-Pirate Library for Arduino IDE: A Complete Setup and Usage Guide

> Learn to set up and use the ESP32-Bit-Pirate library in Arduino IDE. Transform your ESP32-S3 into a Wi-Fi hacking tool with serial, web, and standalone interfaces. Get the guide now.

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

---

**The ESP32-Bit-Pirate firmware turns an ESP32-S3 board into a Wi-Fi-enabled multi-protocol hacking tool through the Arduino framework, offering Serial, Web, and standalone interfaces with a unified command set.**

This open-source project implements a modern successor to the classic Bus Pirate. Built on the Arduino framework (via PlatformIO), it runs on ESP32-S3 hardware and exposes protocols like **I²C**, **SPI**, **UART**, **1-Wire**, **2-Wire**, **CAN**, **Sub-GHz**, and **RFID** through three interchangeable interfaces—all sharing identical commands.

---

## ESP32-Bit-Pirate Architecture Overview

The firmware follows a clean, three-layer design that separates hardware control from protocol logic and user interaction.

### Hardware Abstraction Layer

Drivers for GPIO, buses, radios, and connectivity are distributed across the `src/` directory. The UART sniffer, for example, lives in the UART service class called from [`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp).

### Protocol Services Layer

Each protocol operates as a **mode** (HiZ, I²C, SPI, UART, etc.) with standardized commands: `scan`, `sniff`, `read`, `write`, and EEPROM dumping. The central dispatcher in [`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp) parses input and routes it to the appropriate service handler.

### User Interface Layer

Three interfaces expose identical functionality:

- **Serial CLI** — Default Arduino `Serial` console over USB
- **Web UI** — Browser-based terminal served from [`src/Views/WebTerminalView.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Views/WebTerminalView.cpp) and [`src/Views/WebTerminalView.h`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Views/WebTerminalView.h)
- **Standalone** — Direct M5 Cardputer display and keyboard operation

---

## Installing and Building with Arduino IDE

While the project is developed in PlatformIO, it remains fully compatible with the Arduino IDE because it uses the standard Arduino framework.

### PlatformIO Configuration (Recommended)

The [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini) file defines the build environment:

```ini
[env:esp32-s3-devkit]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
monitor_speed = 115200

```

### Arduino IDE Steps

1. Install the **ESP32 by Espressif Systems** board package (version 2.0.14 or later).
2. Select **Tools → Board → ESP32S3 Dev Module**.
3. Set **Partition Scheme** to **Huge APP** to accommodate the firmware size.
4. Install required libraries: `WebServer`, `WiFi`, `LittleFS`.
5. Copy the `src/` contents to your sketch folder and upload.

---

## Core Commands in the ESP32-Bit-Pirate Library

All three interfaces accept the same command syntax. This design enables scripting and automation across Serial, Web, and standalone modes.

| Command | Function |
|---------|----------|
| `mode <protocol>` | Switch to protocol mode (i2c, spi, uart, etc.) |
| `scan` | Detect devices on the current bus |
| `sniff` | Capture traffic in real time |
| `write <data>` | Transmit data to the target device |
| `read [n]` | Receive n bytes from the target |
| `dump` | Read full EEPROM contents |
| `wifi` | Configure Wi-Fi credentials |
| `script` | Execute bytecode or Python scripts |

---

## Code Examples for Arduino IDE

### Example 1: I²C Bus Scanning

```cpp
void setup() {
  Serial.begin(115200);
  while (!Serial) { ; }  // Wait for USB connection
  
  Serial.println(F("mode i2c"));   // Enter I2C mode
  delay(100);
  Serial.println(F("scan"));       // Scan for devices
}

void loop() {
  // Firmware handles command execution; loop remains empty
}

```

Upload, open the Serial Monitor at 115200 baud, and observe detected addresses.

### Example 2: UART Sniffing with Auto-Baud Detection

```cpp
void setup() {
  Serial.begin(115200);
  while (!Serial) { ; }
  
  Serial.println(F("mode uart"));  // Enter UART mode
  delay(100);
  Serial.println(F("sniff"));      // Start passive monitoring
  // Auto-baud detection eliminates manual configuration
}

void loop() {}

```

The firmware automatically detects baud rates—no ` Serial.begin()` guessing required.

### Example 3: Python Script for Automated Testing

```python
import serial
import time

ser = serial.Serial('/dev/ttyUSB0', 115200, timeout=1)
time.sleep(2)  # Boot delay

ser.write(b'mode spi\n')
ser.write(b'write 0x01 0x80\n')  # Send initialization sequence

ser.write(b'dump\n')

while True:
    line = ser.readline()
    if line:
        print(line.decode().strip())

```

This demonstrates cross-platform scripting using the same command set available in the Arduino IDE Serial Monitor.

---

## Web Interface Activation

The ESP32-Bit-Pirate library serves a browser-based terminal when Wi-Fi is configured:

1. Connect via Serial and run: `wifi <ssid> <password>`
2. Note the assigned IP address in the output
3. Navigate to `http://<esp32_ip>/`
4. The JavaScript console loads from [`src/Views/WebTerminalView.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Views/WebTerminalView.cpp) handlers

All Serial commands work identically in the Web UI—no syntax translation needed.

---

## Extending the ESP32-Bit-Pirate Firmware

The architecture deliberately isolates **command parsing** from **protocol handling**. New protocols are added by:

1. Creating a service class in `src/Services/`
2. Registering commands in the dispatcher at [`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp)
3. Implementing mode-specific handlers (scan, read, write, sniff)

The README's "Contribute" section provides step-by-step guidance for extending the command set.

---

## Key Source Files in the ESP32-Bit-Pirate Repository

| File | Purpose |
|------|---------|
| [`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp) | Entry point, command parser, protocol dispatcher |
| [`src/Views/WebTerminalView.h`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Views/WebTerminalView.h) | Web UI class declaration |
| [`src/Views/WebTerminalView.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Views/WebTerminalView.cpp) | Web terminal rendering and HTTP handlers |
| [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini) | Build configuration for Arduino framework |
| [`test/test_main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/test/test_main.cpp) | Unit tests for command parsing logic |

These paths demonstrate the service-oriented structure that keeps the ESP32-Bit-Pirate library maintainable and extensible.

---

## Advanced Features

- **LittleFS file system** — Persistent storage accessible via HTTP API for logs and configurations
- **Bytecode execution** — Bus Pirate-compatible scripting for complex automation
- **Python scripting** — Direct script execution on the ESP32-S3 without external tooling

---

## Summary

- **ESP32-Bit-Pirate** firmware runs on ESP32-S3 using the standard Arduino framework, compatible with both PlatformIO and Arduino IDE
- Three interfaces (Serial, Web, Standalone) share identical commands: `mode`, `scan`, `sniff`, `write`, `read`, `dump`
- Protocol services are modular; new modes integrate through the dispatcher in [`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp) without modifying core logic
- Auto-baud detection, LittleFS storage, and scripting support enable sophisticated embedded debugging workflows
- Source files follow clear separation: hardware drivers, protocol services, and UI layers in `src/Views/`

---

## Frequently Asked Questions

### How do I install ESP32-Bit-Pirate in the Arduino IDE?

Add the ESP32 board package, select the ESP32-S3 Dev Module, install WebServer/WiFi/LittleFS libraries, and upload the `src/` contents as a sketch. PlatformIO remains the primary development environment but Arduino IDE compatibility is maintained through the `arduino` framework setting in [`platformio.ini`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/platformio.ini).

### Does the Web interface require different commands than Serial?

No. The Web UI built in [`src/Views/WebTerminalView.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/Views/WebTerminalView.cpp) processes identical command strings as the Serial CLI. After configuring Wi-Fi with the `wifi` command, browsing to the device IP presents the same terminal experience.

### What protocols does ESP32-Bit-Pirate support?

I²C, SPI, UART, 1-Wire, 2-Wire, CAN, Wi-Fi, Bluetooth, Sub-GHz radio, and RFID. Each protocol implements consistent commands: `scan` for device discovery, `sniff` for passive monitoring, and read/write for active communication.

### Can I add custom protocol support?

Yes. The dispatcher in [`src/main.cpp`](https://github.com/geo-tp/ESP32-Bit-Pirate/blob/main/src/main.cpp) routes commands to service objects without hardcoded protocol logic. Create a new service class, register its commands, and follow the contribution guidelines in the README to extend the firmware.