geo-tp/ESP32-Bus-Pirate: ESP32 Multi-Protocol Hardware Hacking Tool

geo-tp/ESP32-Bus-Pirate: ESP32 Multi-Protocol Hardware Hacking Tool

When you're debugging an I2C sensor that won't acknowledge, sniffing SPI flash traffic, or probing an unknown UART baud rate, you typically reach for a logic analyzer, a separate USB-to-serial adapter, and maybe a Bus Pirate v3 that's showing its age. The friction stacks up: multiple tools, multiple cables, different software interfaces, and the nagging sense that your bench could be cleaner. geo-tp/ESP32-Bus-Pirate addresses this directly by turning an inexpensive ESP32-S3 development board into a unified multi-protocol development and analysis tool—complete with a web-based CLI that eliminates the need for dedicated terminal software.

This open-source firmware, inspired by the original Bus Pirate, now has 4,323 GitHub stars, 349 forks, and an active commit history with the last update on July 12, 2026. Released under the MIT License and written primarily in C++, it represents a pragmatic evolution of embedded debugging hardware: leverage the ESP32-S3's built-in radios, GPIO flexibility, and USB-OTG to consolidate dozens of tools into one programmable device.

What is geo-tp/ESP32-Bus-Pirate?

geo-tp/ESP32-Bus-Pirate is open-source firmware that transforms ESP32-S3-based development boards into multi-protocol analysis and development tools. The project is maintained by geo-tp and explicitly modeled after the legendary Bus Pirate, the open-hardware debugging tool created by Dangerous Prototypes that became a staple of embedded development workshops worldwide.

The firmware operates in a fundamentally different paradigm from traditional dedicated logic analyzers. Rather than requiring a host PC application like PulseView or Saleae Logic, geo-tp/ESP32-Bus-Pirate exposes its functionality through three interface modes: USB Serial, Wi-Fi Web CLI, and Standalone (for the M5 Cardputer). This architectural choice reflects modern development workflows where browser-based tooling and wireless connectivity reduce cable clutter and enable headless operation.

The project's relevance in 2026 stems from three converging trends: the commoditization of ESP32-S3 modules (with integrated 2.4GHz Wi-Fi, Bluetooth 5 LE, and USB-OTG), the growing complexity of IoT device protocols requiring field debugging, and the maturation of Web Serial APIs that enable sophisticated browser-based hardware interfaces without native application installation.

Unlike commercial tools that lock features behind firmware upgrades or subscription tiers, geo-tp/ESP32-Bus-Pirate's MIT License permits modification, redistribution, and commercial use. The C++ codebase targets the ESP-IDF framework, making it accessible to developers already familiar with Espressif's ecosystem.

Key Features

The firmware's feature set spans 24 distinct operational modes, organized by protocol family rather than by abstraction layer. This design preserves the Bus Pirate's original philosophy: direct, protocol-level access without hiding implementation details behind opaque APIs.

Digital Protocols: I2C (with scan, glitch injection, slave mode, EEPROM dump), SPI (EEPROM, flash, SD card, slave mode), UART/Half-Duplex UART (bridge, read, write, baudrate auto-detection, AT command support), 1-Wire (iButton, EEPROM), 2-Wire/3-Wire (sniffing, smartcard, EEPROM), and DIO (direct GPIO manipulation with PWM and servo control).

Wireless and Radio: Bluetooth (BLE HID, scan, spoofing, sniffing), Wi-Fi/Ethernet (sniff, deauth, nmap, netcat), Sub-GHz (analyze, record, replay), RFID (read, write, clone), RF24 (scan, send, receive), FM (analyze, broadcast), and cellular (SIM dump, SMS, call operations).

Specialized Interfaces: JTAG (scan, SWD, OpenOCD integration), CAN (sniff, send/receive frames), I2S (speaker/mic testing), USB (HID, flashrom, storage, USB-UART), Infrared (80+ protocols via "Device-B-Gone" command, record, universal remote), and LED control (50+ addressable LED protocols).

Infrastructure Features: Protocol sniffers for I2C, UART, SPI, 1-Wire, 2-Wire, CAN, Wi-Fi, Bluetooth, and Sub-GHz; Bus Pirate-style bytecode scripting and Python^{↗ Bright Coding Blog} automation; LittleFS filesystem with HTTP import/export; and the "Pirate assistant" interactive help system. The Web Serial Tools enable browser-based terminal access without PuTTY or minicom installation.

Notably, the firmware supports hardware expanders for additional radio protocols like 5GHz Wi-Fi, and a docking station compatible with original Bus Pirate adapters—preserving investment in existing accessory ecosystems.

Use Cases

IoT Device Prototyping and Debugging: When bringing up a new sensor board, developers typically need I2C scanning to detect device addresses, register dumps to verify configuration, and SPI flash programming for firmware updates. geo-tp/ESP32-Bus-Pirate consolidates these into one device with consistent command syntax across protocols. The web CLI enables wireless debugging of deployed devices without physical access to a USB port.

Security Research and Hardware Assessment: The firmware's sniffing capabilities across wireless protocols (Wi-Fi, Bluetooth, Sub-GHz, RFID) and wired buses (I2C, SPI, UART, CAN) support methodical hardware security assessment. The deauth and spoofing functions, explicitly framed for authorized testing in the project's warning, enable controlled evaluation of wireless device behavior under attack conditions. JTAG/SWD access facilitates firmware extraction from locked devices where permitted.

Automated Testing and Manufacturing: Python scripting over serial enables integration into CI pipelines for hardware-in-the-loop testing. The bytecode instruction set provides deterministic timing for production-line programming tasks—flashing EEPROMs, verifying LED installations, or testing audio I2S outputs—without the overhead of a full Python interpreter on the host.

Field Service and Reverse Engineering: The standalone mode on M5 Cardputer creates a portable, battery-powered analysis tool. Technicians can capture unknown infrared remote signals, identify UART console ports on mystery hardware, or dump 1-Wire iButton credentials for legitimate backup purposes. The Sub-GHz record/replay supports analyzing proprietary wireless protocols in industrial environments.

Educational Environments: The consistent command structure across protocols reduces cognitive load for students learning embedded systems. Browser-based access eliminates cross-platform toolchain installation barriers, while the open-source nature permits curriculum customization.

Installation & Setup

The project provides two primary installation paths: browser-based web flashing and M5Burner for M5Stack devices.

Web Flasher (Recommended)

Navigate to the ESP32 Bit Pirate Web Flasher in a Chrome, Edge, or Opera browser (Web Serial API required). Connect your ESP32-S3 board via USB, select the matching device profile, and flash directly—no esptool.py installation needed.

For boards not in the explicit device list, flash the ESP32-S3 Dev Kit firmware. The project notes that "all boards based on the ESP32-S3 can be supported, provided they have at least 8 MB of flash," though default pin mappings may require adjustment.

M5Burner (M5Stack Devices)

For M5 AtomS3, StampS3, StickS3, or Cardputer variants, use M5Burner and select the appropriate device category.

Connection Methods

After flashing, access the CLI through either:

# Serial connection: any terminal at default baudrate
# Or browser-based: https://geo-tp.github.io/ESP32-Bit-Pirate/web-tools/web-serial-terminal/

# Wi-Fi Web CLI: configure wireless credentials, then access via browser
# Documentation: https://github.com/geo-tp/ESP32-Bit-Pirate/wiki/00-Terminal

First Commands

mode      # Display or change current protocol mode
help      # List available commands for current mode
scan      # Scan for devices (I2C, Bluetooth, Wi-Fi, etc.)
sniff     # Enter protocol-specific sniffer

The wiki provides mode-specific command references; the Terminal mode page covers serial and web terminal configuration in detail.

Real Code Examples

The README emphasizes interactive CLI usage over traditional "code" in the programming sense. The command structure follows Bus Pirate conventions. Here are documented patterns with explanations:

Basic Mode Selection and I2C Scan

# Enter I2C mode from default HiZ (high impedance) state
mode i2c

# Scan for responding devices on the bus
scan

# Typical output: device addresses in 7-bit format
# 0x50 - EEPROM detected
# 0x68 - RTC module detected

This sequence demonstrates the firmware's discovery-first approach. The mode command switches electrical configurations and available command sets, while scan automates address probing without manual register writes.

UART Baudrate Auto-Detection and Bridge

# Enter UART mode
mode uart

# Enable automatic baudrate detection
baudrate auto

# Bridge mode: transparently forward between UART and USB/Serial
bridge

# Exit bridge with Bus Pirate standard sequence (typically Ctrl+A then menu)

The auto-detection eliminates guesswork when interfacing with undocumented hardware. Bridge mode creates a passive conduit useful for intercepting traffic between two devices or extending serial access wirelessly via the web CLI.

Python Scripting for Automated EEPROM Dump

# Python script executed over serial via ESP32 Bit Pirate Python Lab
# https://geo-tp.github.io/ESP32-Bit-Pirate/web-tools/python-lab/

import serial
import time

# Open connection to Bit Pirate
bp = serial.Serial('/dev/ttyACM0', 115200, timeout=1)

# Enter I2C mode
bp.write(b'mode i2c\n')
time.sleep(0.5)

# Dump 256 bytes from EEPROM at address 0x50
bp.write(b'[0x50 0x00 [0x51 r:256]]\n')
response = bp.read(1024)

# Save to file
with open('eeprom_dump.bin', 'wb') as f:
    f.write(response)

This example reflects the project's Python scripting documentation. The bracket syntax [0x50 0x00 [0x51 r:256]] uses Bus Pirate-style bytecode: start condition, write device address with write bit, write memory address, repeated start, read device address with read bit, read 256 bytes. The Python Lab provides browser-based script development without local Python installation.

Note: The README does not contain extensive "copy-paste" code blocks beyond command sequences and the general Python scripting reference. Developers should consult the wiki for comprehensive command syntax per mode.

Advanced Usage & Best Practices

Pin Mapping Verification: When using the generic ESP32-S3 Dev Kit firmware on non-standard boards, verify GPIO assignments against your specific hardware. The firmware's defaults target common devkit pinouts; mismatches will cause silent failures rather than explicit errors.

Interface Selection Trade-offs: The web CLI eliminates cable dependencies but introduces Wi-Fi latency unsuitable for high-speed SPI flash extraction. For bulk data operations, prefer USB Serial. The web interface excels for configuration, monitoring, and scenarios where physical access is limited.

Voltage Discipline: The firmware operates at 3.3V or 5V only. The README explicitly warns against other voltage levels—ESP32-S3 GPIO pins are not 5V-tolerant, and connecting 1.8V or 12V logic will damage the device. Level shifters are mandatory for mixed-voltage environments.

Legal and Ethical Boundaries: The RF transmission capabilities (Sub-GHz, Wi-Fi deauth, Bluetooth spoofing) are powerful and potentially regulated. The project's warning emphasizes educational and authorized testing purposes only. Researchers should verify local spectrum regulations and obtain proper authorization before transmitting.

Filesystem Management: LittleFS over HTTP enables convenient data export, but consider security implications if operating on sensitive captures. The web server binds to all interfaces by default when Wi-Fi is enabled—evaluate network exposure in production environments.

Comparison with Alternatives

g eo-tp/ESP32-Bus-Pirate occupies a distinct niche: maximum protocol breadth at minimal hardware cost, with open-source flexibility that commercial tools cannot match. The trade-off is polish—configuration requires more manual effort than Flipper Zero's guided workflows, and protocol decoding depth lags behind dedicated logic analyzers for complex signal analysis.

FAQ

What ESP32 boards are supported? ESP32-S3 boards with minimum 8MB flash. Explicitly tested: ESP32-S3 Dev Kit, LILYGO T-Display/T-Embed variants, M5 AtomS3/StampS3/StickS3/Cardputer, Seeed Studio Xiao S3.

Can I use this on original ESP32 or ESP32-C3? The README specifies ESP32-S3 only, leveraging its USB-OTG and performance features. Other variants are not documented.

Is the web CLI secure? No authentication is mentioned in the README. Treat Wi-Fi access as equivalent to physical serial access—use isolated networks for sensitive operations.

How does licensing affect commercial use? MIT License permits commercial use, modification, and distribution with attribution. No GPL copyleft requirements.

What's the performance for SPI flash dumping? Specific throughput numbers are not documented. USB Serial mode will outperform Wi-Fi for bulk transfers.

Can I contribute new protocols? Yes—the wiki outlines a "simple way to add a new command to any mode." The C++ codebase uses ESP-IDF patterns familiar to ESP32 developers.

Does it replace my oscilloscope? No. It complements scopes and logic analyzers with interactive protocol-level access and signal generation that passive tools cannot provide.

Conclusion

geo-tp/ESP32-Bus-Pirate delivers genuine utility for embedded developers, security researchers, and hardware hackers who need protocol versatility without dedicated equipment budgets. Its 4,323-star GitHub presence and active 2026 development indicate community validation beyond novelty. The firmware rewards users comfortable with command-line interfaces and protocol fundamentals; those seeking guided graphical workflows may prefer commercial alternatives.

The project is best suited for: developers building ESP32-based products needing field debug tools, researchers conducting authorized hardware security assessments, educators teaching embedded protocols, and makers consolidating bench equipment. The MIT License and open hardware expander ecosystem provide long-term viability absent from closed-source competitors.

For protocol breadth per dollar, wireless integration, and hackability, geo-tp/ESP32-Bus-Pirate merits serious consideration. Explore the repository, flash the web flasher, and verify against your specific use case before committing to alternative tooling.

For related embedded development workflows, see [INTERNAL_LINK: ESP32 development environment setup] or [INTERNAL_LINK: hardware security testing methodology].