🦈 Bruce

Bruce is a versatile ESP32 firmware packed with offensive-security tools, built to make Red Team operations fast and portable.

It also supports M5Stack, LILYGO , RockBase IoT and Elecrow products, and works great with the Cardputer, Sticks, M5Cores, T-Decks and T-Embeds.

⚡ Get Our Official DevKit!

RF REAPER

RF REAPER is our custom PCB devkit, purpose-built for Bruce!

Every major feature works natively, right out of the box. Sub-GHz, NFC/RFID, IR, 2.4GHz(NRF), GPS-ready, and a microSD, all driven by a beefy ESP32-S3 (16MB Flash / 8MB PSRAM). Tons of GPIOs via the AW9523 expander plus Flipper Zero & iButton header compatibility mean you can hack, mod, and build on it endlessly. Want a specific function? Ask us with an issue, we'll check it.

👉 Buy the RF REAPER and official boards

Check our fully open-source hardware too: https://bruce.computer/boards

More custom devkit boards coming soon! Stay across our communities!

🏗️ How to install

source ~/.espressif/v6.0.2/esp-idf/export.sh
idf.py -p PORT flash

🛠️ How to build

Install ESP-IDF and follow the instructions to build Bruce.

then build by sourcing the ESP-IDF environment and running:

source ~/.espressif/v6.0.2/esp-idf/export.sh
idf.py build

This builds the default board (M5 Cardputer). To build for a specific board, use tools/board.py instead, which picks the right chip target and board-specific sdkconfig.defaults (see boards/<board>/) and puts the build output in its own build-board/<board>/ directory:

source ~/.espressif/v6.0.2/esp-idf/export.sh
python tools/board.py --list                 # show available board ids
python tools/board.py m5stack-cplus2 build
python tools/board.py m5stack-cplus2 flash monitor -p PORT

🧪 How to run tests

Perequisites:

source ~/.espressif/v6.0.2/esp-idf/export.sh
python -m pip install pytest pytest-embedded pytest-embedded-idf pytest-embedded-qemu
python $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv32

Then run the tests with:

source ~/.espressif/v6.0.2/esp-idf/export.sh
idf.py -B build-qemu build
python -m pytest tests/pytest_firmware.py

The QEMU image boots to the same interactive shell a real serial console would, then launches selftest on it (this is the one bit of test-running behavior baked into a QEMU test-mode boot -- QEMU's emulated serial link only carries firmware output back to the host in this setup, not typed input to the firmware, so the test can't just type the command itself once the shell's up). Pass --selftest-filter (repeatable) to run only cases whose name contains the given text, instead of the full suite -- this reconfigures and rebuilds build-qemu/ with the matching boot command before the image boots, so expect a rebuild the first time you use it (or switch back):

python -m pytest tests/pytest_firmware.py --selftest-filter=notification

docs/COMMANDS.md is generated the same way, from the firmware's own man --gen-md:

python tools/gen_commands_doc.py

⌨️ Discord Server

📑 Wiki

For more information on each function supported by Bruce, read our wiki here. Also, read our FAQ

💻 List of Features BrucePIO supports

WiFi

BLE

RF

RFID

IR

TV-B-Gone
IR Receiver
Custom IR (NEC, NECext, SIRC, SIRC15, SIRC20, Samsung32, RC5, RC5X, RC6)
Config - [X] Ir TX Pin - [X] Ir RX Pin

FM

NRF24

NRF24 Jammer
2.4G Spectrum
Mousejack

Scripts

JavaScript Interpreter Credits to justinknight93

Others

Clock

RTC Support
NTP time adjust
Manual adjust

Connect (ESPNOW)

Send File
Receive File
Send Commands
Receive Commands

Config

Specific functions per Device, the ones not mentioned here are available to all.

Device	CC1101	NRF24	FM Radio	PN532	Mic	BadUSB	RGB Led	Speaker	Fuel Gauge	LITE_VERSION
M5Stack Cardputer (and ADV)	🆗	🆗	🆗	🆗	🆗	🆗	🆗	NS4168	❌	❌
M5Stack M5StickC PLUS2	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	Tone	❌	❌
M5Stack M5StickC PLUS	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	Tone	❌	❌²
M5Stack M5Core BASIC	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	Tone	❌	❌
M5Stack M5Core2	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	❌	❌	❌
M5Stack M5CoreS3/SE	🆗	🆗	🆗	🆗	❌	🆗	❌	❌	❌	❌
JCZN CYD‑2432S028	🆗	🆗	🆗	🆗	❌	🆗¹	❌	❌	❌	❌²
Lilygo T‑Embed CC1101	🆗	🆗	🆗	🆗	🆗	🆗	🆗	🆗	🆗	❌
Lilygo T‑Embed	🆗	🆗	🆗	🆗	🆗	🆗	🆗	🆗	❌	❌
Lilygo T-Display-S3	🆗	🆗	❌	❌	❌	🆗	❌	❌	❌	❌
Lilygo T‑Deck (and pro)	🆗	❌	❌	❌	❌	🆗	❌	❌	❌	❌
Lilygo T-Watch-S3	❌	❌	❌	❌	❌	🆗	❌	❌	❌	❌
Lilygo T-LoRa Pager	❌	❌	❌	❌	❌	🆗	❌	❌	❌	❌
Smoochiee V2	🆗	🆗	❌	🆗	❌	🆗	❌	❌	❌	❌
ESP32-C5	🆗	🆗	❌	🆗	❌	❌	❌	❌	❌	❌
Bruce RF Reaper	🆗	🆗	❌	🆗 but w/ ST25R3916	❌	🆗	🆗	❌	🆗	❌
Elecrow 24B	🆗	🆗	🆗	🆗	❌	🆗¹	❌	❌	❌	❌²
Elecrow 3.5"	🆗	🆗	🆗	🆗	❌	🆗¹	❌	❌	❌	❌²
NM-CYD-C5 + RF HAT	🆗	🆗	❌	🆗	❌	🆗	🆗	❌	🆗	❌
² CYD have a LITE_VERSION version for Launcher Compatibility
¹ Core, CYD and StickCs Bad-USB: here

LITE_VERSION: TelNet, SSH, WireGuard, ScanHosts, RawSniffer, Brucegotchi, BLEBacon, BLEScan and Interpreter are NOT available for M5Launcher Compatibility

✨ Why and how does it look?

Bruce stems from a keen observation within the community focused on devices like Flipper Zero. While these devices offered a glimpse into the world of offensive security, there was a palpable sense that something more could be achieved without being that overpriced, particularly with the robust and modular hardware ecosystem provided by ESP32 Devices, Lilygo and M5Stack products.

Other media can be found here.

👏 Acknowledgements

@bmorcelli for new core and a bunch of new features, also porting to many devices!
@IncursioHack for adding RF and RFID modules features.
@Luidiblu for logo and UI design assistance.
@eadmaster for adding a lot of features.
@rennancockles for a lot of RFID code, refactoring and others features.
@7h30th3r0n3 refactoring and a lot of help with WiFi attacks.
@Tawank refactoring interpreter among many other things
@pablonymous RF functions to read RAW Data
Smoochiee for Bruce PCB design.
TH3_KR4K3N for Stick cplus extender PCB design.
Everyone who contributed in some way to the project, thanks ❤️

Bruce also stands on the shoulders of other great open-source firmware projects, which inspired features and code across the project:

ESP32Marauder by @justcallmekoko — WiFi/Bluetooth offensive toolkit.
Launcher by @bmorcelli — the multi-app launcher/bootloader for the devices.
Evil-M5Project by @7h30th3r0n3 — WiFi attack suite for M5Stack.
M5Stick-Nemo by @n0xa — multi-tool firmware for M5Stick devices.

Bruce builds on many free-software libraries, and parts of the RF and NFC/RFID modules are derived from other projects. See THIRD_PARTY.md for third-party attribution and copyleft-compliance details.

🚧 Disclaimer

Bruce is a tool for cyber offensive and red team operations, distributed under the terms of the Affero General Public License (AGPL). It is intended for legal and authorized security testing purposes only. Use of this software for any malicious or unauthorized activities is strictly prohibited. By downloading, installing, or using Bruce, you agree to comply with all applicable laws and regulations. This software is provided free of charge, and we do not accept payments for copies or modifications. The developers of Bruce assume no liability for any misuse of the software. Use at your own risk.

Tawank/BruceOS

README