Bruce Custom Firmware — Enhanced App Platform

A custom fork of the Bruce firmware for the LilyGo T-Embed CC1101, adding a Flipper Zero-style app loading system with full hardware access and expanded memory for JavaScript apps.

Original Bruce firmware: https://github.com/BruceDevices/firmware

All credit for the base firmware goes to the Bruce team and contributors. This fork builds on top of their work.

---

What's New in This Fork

Apps Menu

• New Apps menu in the main menu
• Automatically discovers apps from the /apps/ directory on SD card or LittleFS
• Each app uses a manifest.json to define its name, version, category, and entry point
• Launch apps directly from the menu

Memory Improvements

• JS interpreter heap increased from 64KB to 512KB using PSRAM (with automatic fallback)
• Task stack size increased from 8KB to 16KB for more complex scripts

New JavaScript API Modules

BLE (ble module)

• ble.scan(duration) — Scan for nearby BLE devices, returns array of results
• ble.advertise(name, duration) — Broadcast as a BLE device

NRF24 (nrf24 module)

• nrf24.begin(cePin, csnPin) — Initialize the RF24 radio
• nrf24.setChannel(ch) — Set RF channel (0–125)
• nrf24.openReadPipe(pipe, address) / nrf24.openWritePipe(address)
• nrf24.startListening() / nrf24.stopListening()
• nrf24.available() / nrf24.read(length) / nrf24.write(data)

LED (led module)

• led.setColor(r, g, b) — Set RGB LED color
• led.setBrightness(value) — Set brightness (0–255)
• led.off() — Turn LED off
• led.blink(delay_ms) — Blink once

Menu (menu module)

• menu.show(title, options) — Display a native Bruce menu, returns selected index
• menu.alert(title, message) — Show an alert dialog
• menu.confirm(title, message) — Show yes/no confirmation, returns boolean

---

Creating an App

1. Create a folder on your SD card under /apps/, e.g. /apps/my_app/
2. Add a manifest.json:

{
  "name": "My App",
  "description": "What my app does",
  "entry": "main.js",
  "category": "Tools",
  "version": "1.0"
}

3. Add your main.js script (or whatever you named the entry point)

Example App

// /apps/led_demo/main.js
led.setColor(255, 0, 0);
led.setBrightness(128);

var choice = menu.show("LED Demo", ["Red", "Green", "Blue", "Off"]);
if (choice === 0) led.setColor(255, 0, 0);
else if (choice === 1) led.setColor(0, 255, 0);
else if (choice === 2) led.setColor(0, 0, 255);
else led.off();

---

Flashing

Put your T-Embed CC1101 into bootloader mode (hold BOOT, press RESET, release BOOT), then:

esptool.py --chip esp32s3 --port COMx write_flash 0x0 Bruce-lilygo-t-embed-cc1101.bin

Replace COMx with your actual COM port.

---

Device Compatibility

The code changes live in shared source files, so they should compile for all Bruce-supported devices. However, some features are hardware-dependent:

Works on all devices:

• Apps menu and app launcher (uses standard SD/LittleFS + JS interpreter)
• Memory improvements (PSRAM heap uses ps_malloc with automatic fallback for devices without PSRAM)
• Menu JS module (uses Bruce's native UI — fully device-agnostic)
• BLE JS module (NimBLE is available on all ESP32 variants)

Hardware-dependent:

• LED module — Wrapped in #ifdef HAS_RGB_LED. Compiles on all devices but only functions on those with RGB LEDs (T-Embed CC1101, Cardputer, Bruce RF Reaper, etc.)
• NRF24 module — Only useful on devices with NRF24 hardware connected

Notes:

• LITE_VERSION builds will not include any of the new features (guarded by #if !defined(LITE_VERSION) && !defined(DISABLE_INTERPRETER))
• Only the lilygo-t-embed-cc1101 target has been built and tested so far. Other targets should work but may need testing.

---

Building From Source

Prerequisites

1. Python 3.x — https://www.python.org/downloads/
2. PlatformIO Core (CLI) — Install via pip:

   pip install platformio

3. GCC (for JS header generation) — The build uses a host GCC to pre-compile JavaScript headers.
   • Windows: Install MSYS2 (https://www.msys2.org/), then run pacman -S mingw-w64-i686-gcc in the MSYS2 terminal. The GCC will be at C:\msys64\mingw32\bin\gcc.exe.
   • Linux/macOS: GCC is usually already installed (gcc in PATH).
4. Git — https://git-scm.com/downloads

Clone and Build

git clone https://github.com/jsauce454/bruce-customfw.git
cd bruce-customfw

Windows (PowerShell):

$env:MQJS_HOST_CC = "C:\msys64\mingw32\bin\gcc.exe"
pio run -e lilygo-t-embed-cc1101

Linux / macOS:

export MQJS_HOST_CC=gcc
pio run -e lilygo-t-embed-cc1101

The output binary will be at Bruce-lilygo-t-embed-cc1101.bin in the project root.

Building for Other Devices

Replace the -e target with any supported Bruce environment:

pio run -e m5stack-cardputer
pio run -e m5stack-m5stickc-plus2
pio run -e lilygo-t-deck
pio run -e lilygo-t-embed
pio run -e m5stack-core2

Check platformio.ini for the full list of available build environments.

First Build Notes

• The first build takes several minutes as PlatformIO downloads all toolchains and dependencies automatically.
• The patch.py pre-build script will automatically patch libnet80211.a (weakens a symbol to allow custom WiFi attack code). This only runs once and creates a .patched flag.
• If the build fails with cannot find -lnet80211, delete the .patched file in your PlatformIO framework libs directory and rebuild.

---

Original Bruce Features

This fork includes all features from the original Bruce firmware. See the original README for the full feature list, including:

💻 List of Features

WiFi

• Connect to WiFi
• WiFi AP
• Disconnect WiFi
• WiFi Atks
  • Beacon Spam
  • Target Atk
    • Information
    • Target Deauth
    • EvilPortal + Deauth
  • Deauth Flood (More than one target)
• Wardriving
• TelNet
• SSH
• RAW Sniffer
• TCP Client
• TCP Listener
• Evil Portal
• Scan Hosts (with TCP Port scanning)
• Responder
• Arp Spoofing
• Arp Poisoning
• Wireguard Tunneling
• Brucegotchi
  • Pwnagotchi friend
  • Pwngrid spam faces & names
    • [Optional] DoScreen a very long name and face
    • [Optional] Flood uniq peer identifiers

BLE

• BLE Scan
• Bad BLE - Run Ducky scripts, similar to BadUsb
• BLE Keyboard - Cardputer and T-Deck Only
• iOS Spam
• Windows Spam
• Samsung Spam
• Android Spam
• Spam All

RF

• Scan/Copy
• Custom SubGhz
• Spectrum
• Jammer Full (sends a full squared wave into output)
• Jammer Intermittent (sends PWM signal into output)
• Config
  • RF TX Pin
  • RF RX Pin
  • RF Module
    • RF433 T/R M5Stack
    • CC1101 (Sub-Ghz)
  • RF Frequency
• Replay

RFID

• Read tag
• Read 125kHz
• Clone tag
• Write NDEF records
• Amiibolink
• Chameleon
• Write data
• Erase data
• Save file
• Load file
• Config
  • RFID Module
    • PN532
    • PN532Killer
• Emulate tag

IR

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

FM

• Broadcast standard
• Broadcast reserved
• Broadcast stop
• FM Spectrum
• Hijack Traffic Announcements
• Config

NRF24

• NRF24 Jammer
• 2.4G Spectrum
• Mousejack

Scripts

• JavaScript Interpreter Credits to justinknight93

Others

• Mic Spectrum
• QRCodes
  • Custom
  • PIX (Brazil bank transfer system)
• SD Card Mngr
  • View image (jpg)
  • File Info
  • Wigle Upload
  • Play Audio
  • View File
• LittleFS Mngr
• WebUI
  • Server Structure
  • Html
  • SDCard Mngr
  • Spiffs Mngr
• Megalodon
• BADUsb (New features, LittleFS and SDCard)
• USB Keyboard - Cardputer and T-Deck Only
• iButton
• LED Control

Clock

• RTC Support
• NTP time adjust
• Manual adjust

Connect (ESPNOW)

• Send File
• Receive File
• Send Commands
• Receive Commands

Config

• Brightness
• Dim Time
• Orientation
• UI Color
• Boot Sound on/off
• Clock
• Sleep
• Restart

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 Guage	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	❌	🆗	🆗	❌	🆗	❌

² 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 new 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 ❤️

🚧 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.