ESP32-Bit-Pirate README

The project's README from github.com/geo-tp/ESP32-Bit-Pirate. As one markdown file: README.md.

ESP32 Bit Pirate

Logo banner of the ESP32 Bit Pirate firmware

ESP32 Bit Pirate is open-source firmware that turns your device into a multi-protocol development and analysis tool, inspired by the legendary Bus Pirate.

It supports sniffing, sending, scripting, and interacting with various digital protocols (I2C, UART, 1-Wire, SPI, etc.) via a serial terminal or web-based CLI. It also communicates with radio protocols like Bluetooth, Wi-Fi, Sub-GHz, LoRa and RFID.

The official project website centralizes everything: ESP32 Bit Pirate Website.

From there you can install the firmware, open the web tools, follow hardware guides, explore recipes, and access the documentation.

Demo showing the different mode of the ESP32 Bit Pirate firmware The ESP32 Bit Pirate Web Serial Tools

Features

Supported Devices

All boards listed below offer the exact same Bit Pirate features, with no differences in functionality or development status. Some features may require additional hardware.

Device Description
ESP32 S3 Dev Kit (N8, N8R2, N8R8, N16R8...) Photo of the ESP32 S3 Dev Kit More than 20 available GPIO, 1 button
ESP32 S3 Zero / Super Mini Photo of the ESP32 S3 SUPERMINI 15 GPIO (exposed pins), 1 button
M5 AtomS3 Lite Photo of the M5 Atom S3 Lite 8 GPIO (Grove, Header), IR TX, 1 buttton
M5 Cardputer Photo of the M5 Cardputer 2 GPIO (Grove), screen, keyboard, mic, speaker, IR TX, SD card, battery, standalone mode
M5 Cardputer ADV Photo of the M5 Cardputer ADV 12 GPIO (Grove, Header), screen, keyboard, mic, speaker, IR TX, SD card, IMU, battery, Lora, CC1101, standalone mode
M5 StampS3 Photo of the M5 StampS3 9 GPIO (exposed pins), 1 button
M5 Stick S3 Photo of the M5 Stick S3 13 GPIO (Grove, Header), screen, mic, speaker, IR TX, IR RX, IMU, 3 buttons, battery
LILYGO T-Display Photo of the T-Display-S3 13 GPIO (1 Qwicc), screen, 2 buttons
LILYGO T-Embed Photo of the LILYGO T-Embed 9 GPIO (Grove, Header), screen, encoder, speaker, mic, SD card
LILYGO T-Embed CC1101 Photo of the LILYGO T-Embed CC1101 4 GPIO (2x Qwiic), screen, encoder, speaker, mic, SD Card, CC1101, PN532, IR TX, IR RX , battery
LILYGO T-Embed CC1101 Plus Photo of the LILYGO T-Embed CC1101 Plus 4 GPIO (2x Qwiic), screen, encoder, speaker, mic, SD Card, CC1101, NRF24, PN532, IR TX, IR RX , battery
Heltec WiFi LoRa 32 V4 Photo of the Heltec WiFi LoRa 32 V4 15 GPIO (Header), SX1262 LoRa, 2 buttons, screen not supported
Heltec Vision Master T190 Photo of the Heltec Vision Master T190 15 GPIO (Header, Qwiiic), screen, 2 buttons, SX1262 LoRa
Seeed Studio Xiao S3 Photo of the Seeed Studio Xiao ESP32-S3 9 GPIO (exposed pins), 1 button
Waveshare ESP32-S3-GEEK Photo of the Waveshare ESP32-S3-GEEK 7 GPIO (Dupont header), screen, 1 button, SD card
Unexpected Maker ProS3 Photo of the Unexpected Maker ProS3 More than 20 available GPIO (Header, STEMMA QT), 1 button

Getting Started

Banner of the ESP32 Bit Pirate web flasher

  1. 🔧 Flash the firmware

  2. 🔌 Connect via Serial or Web

  3. 🧪 Use commands like:

    mode
    help
    scan
    sniff
    ...
    

Wiki

Banner of the ESP32 Bit Pirate Wiki page

📚 Visit the Wiki for detailed documentation on every mode and command.

Includes:

The wiki is the best place to learn how everything works.

Scripting

Banner of the ESP32 Bit Pirate Scripts page

🛠️ Automate interactions with the ESP32 Bit Pirate using Python scripts over serial.

You can write and test scripts directly in the browser with the ESP32 Bit Pirate Python Lab.

Including: Logging data in a file, eeprom and flash dump, interracting with GPIOs, LED animation...

Expander

Banner of the ESP32 Bit Pirate Expander page

🔌 Expand the capabilities of the ESP32 Bit Pirate with additional hardware modules. The Expander adds support for the WiFi 5 GhZ, Zigbee or other radio protocols.

A Cardputer connected to an expander C5

Dock

Banner of the ESP32 Bit Pirate Dock page

🔧 A docking station for the ESP32 S3 DevKit designed to work with original Bus Pirate adapters. It allows you to plug and use the original Bus Pirate ecosystem of adapters and accessories.

The ESP32 Bit Pirate dock board

Get the ESP32 Bit Pirate Dock on PCBWay.

PCBWay Logo

Command-Line Interfaces

The ESP32 Bit Pirate firmware provides three command-line interface (CLI) modes:

Interface Advantages Ideal for...
Web Interface - Accessible from any browser
- PC, tablets, mobiles
- Works over Wi-Fi
- No cables needed
Quick tests, demos, headless setups
Serial Interface - Faster performance
- Instant responsiveness
- Handles large data smoothly
Intensive sessions, frequent interactions
Standalone - Only for the Cardputer
- On device keyboard
- On device screen
Portable sessions, Quick tests

All interfaces share the same command structure and can be used interchangeably (more details).

Mobile Web Interface over WiFi

An iPhone screenshot showing the Bit Pirate firmware web interface

Standalone Mode for the Cardputer

A Cardputer running the ESP32 Bit Pirate in standalone mode

Contribute

See How To Contribute section, which outlines a simple way to add a new board or a new command.

Visuals Assets

Small logo of the ESP32 Bit Pirate firmware

See images, logo, presentations, photo, video, illustrations. These visuals can be freely used in blog posts, documentation, videos, or articles to help explain and promote the firmware.

Warning

⚠️ Voltage Warning: Devices should only operate at 3.3V or 5V.

  • Do not connect peripherals using other voltage levels — doing so may damage your ESP32.

⚠️ Usage Warning: This firmware is provided for educational, diagnostic, and interoperability testing purposes only.

  • Do not use it to interfere with, probe, or manipulate devices without proper authorization.
  • Avoid any unauthorized RF transmissions (e.g., sub-GHz) that could violate local regulations or disrupt networks and communications.
  • The authors are not responsible for any misuse of this software or hardware, including legal consequences resulting from unauthorized access or signal emission.
  • Always stay within the bounds of your country’s laws and responsible disclosure policies.

ESP32-Bit-Pirate (geo-tp/ESP32-Bit-Pirate)

Searching Database…

Что это такое?ESP32 Bit Pirate — это прошивка с открытым исходным кодом, которая превращает плату ESP32-S3 в многофункциональный инструмент для аппаратного взлома и разработки с поддержкой разных протоколов. Идея навеяна Bus Pirate: вы можете прослушивать, отправлять и писать скрипты для цифровых и радиопротоколов.
Это приложение, которое я устанавливаю, или прошивка, которую я записываю на устройство?Это прошивка, которую вы записываете на поддерживаемую плату ESP32-S3, а затем управляете ею через серийный терминал или веб-CLI. Это не приложение для компьютера.
Как мне записать прошивку на плату?С помощью ESP32 Bit Pirate Web Flasher прошивку можно записать прямо из браузера, а для категорий StickS3, AtomS3, StampS3 или Cardputer — через M5Burner. Затем подключитесь по USB-serial или настройте Wi-Fi, чтобы попасть в веб-CLI.
Какое железо мне нужно, чтобы это запустить?Подойдёт любая плата на ESP32-S3 с флеш-памятью минимум 4 МБ, например ESP32 S3 Dev Kit, M5 Cardputer, LILYGO T-Embed, платы Heltec LoRa и несколько других, перечисленных в README.
Есть ли подводные камни, прежде чем я начну проверять устройства?Распиновка GPIO по умолчанию может не совпадать с вашей конкретной платой, у некоторых плат (например, Heltec WiFi LoRa 32) нет поддержки экрана, а сама прошивка предназначена строго для обучения и авторизованного тестирования — не для несанкционированной радиопередачи или вмешательства в работу устройств.
На каких платах доступны все функции?Все перечисленные платы (ESP32 S3 Dev Kit, M5 AtomS3/Cardputer/StampS3/StickS3, LILYGO T-Display/T-Embed, платы Heltec, Xiao S3, Waveshare GEEK, ProS3) имеют одинаковый набор функций; лишь дополнительное железо — экраны, LoRa-модули или слоты для SD-карт — добавляет удобства.
Что за Bus Pirate, на который он похож?Bus Pirate — известный инструмент с открытым исходным кодом для отладки железа: он позволяет общаться с микросхемами по протоколам вроде I2C и SPI. ESP32 Bit Pirate реализует ту же идею мультипротокольного CLI на дешёвом железе ESP32-S3.
Можно ли автоматизировать задачи, а не вводить команды вручную?Да, вы можете писать скрипты на Python, которые работают с устройством по серийному порту, и проверять их прямо в браузере через ESP32 Bit Pirate Python Lab — например, для дампа EEPROM/флеш-памяти или управления анимациями светодиодов.
Что делает модуль Expander?Expander — это аппаратный модуль-дополнение, который добавляет поддержку радио-возможностей вроде 5 ГГц Wi-Fi и Zigbee, с которыми базовые платы ESP32-S3 сами по себе справиться не могут.
Для чего нужен аксессуар Dock?Dock — это док-станция для ESP32 S3 DevKit, которая позволяет подключать и использовать экосистему переходников и аксессуаров оригинального Bus Pirate.
Creator
geo-tp
Size
328.1 MB
Stars
6.1K
Age
1y
Commits · 90 Days