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

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.

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 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 and 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 file defines the build environment:

[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

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

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

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 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
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	Entry point, command parser, protocol dispatcher
src/Views/WebTerminalView.h	Web UI class declaration
src/Views/WebTerminalView.cpp	Web terminal rendering and HTTP handlers
platformio.ini	Build configuration for Arduino framework
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 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.

Does the Web interface require different commands than Serial?

No. The Web UI built in 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 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.

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