Repository navigation
Getting Started
This guide takes you from a blank device to a connected Brucia setup.
For authorized security research and education only. You are responsible for complying with all applicable laws and for only testing systems you own or are explicitly permitted to test.
- A LilyGo T-Embed CC1101 (ESP32-S3) - the supported, hardware-verified board.
- A data USB-C cable (not a charge-only cable).
- An Android phone and a USB-C OTG cable to connect it to the device.
- Optional: a PN532 module for NFC, an NRF24 QWIIC add-on.
Pick one method.
- Open https://1vcian.me/Brucia/ in Chrome or Edge (desktop, or Chrome on Android via USB-OTG).
- Plug in the T-Embed CC1101 with a data USB-C cable.
- Click Connect & Flash.
This uses Web Serial / ESP Web Tools and flashes the merged, ready-to-use image. Once Brucia is installed, later firmware updates can also be flashed over USB from the app's Updates screen.
pio run -e lilygo-t-embed-cc1101 -t uploadSee Building for the full toolchain setup.
-
Download the APK from the project Releases and install it (allow installation from unknown sources), or
-
Build it yourself:
cd android && ./gradlew :app:assembleDebug
Requires JDK 17 or newer (21/23 tested). See Building.
Brucia offers two ways to use the device from the phone.
- On the device, tap Brucia on the home screen. It shows a QR code to get the app, then "waiting for app".
- Plug the device into the phone with a USB-C OTG cable.
- Open the Brucia app and tap Connect over USB.
- The status pill turns green and the device dashboard card shows board, chip, modules and live battery percentage.
In companion mode the device becomes a radio/sensor front-end and the phone does the
heavy work. This is where the native offload screens (Wardrive, Crack, and the rest)
operate. The app opens on a dashboard with a bottom navigation bar, and every
page is capability-gated: when the device reports its caps{} object, the app shows
only the modules the attached board actually has (so NFC, NRF24, mic, speaker and FM
pages appear only when that hardware is present).
If you want to drive the real device UI from the phone instead:
- Leave the device on its normal menu (do not enter Brucia/companion mode).
- Open the Remote tab in the app and tap Start.
- A D-pad drives the real device UI and the device screen is mirrored live in the app.
This reaches every standalone Bruce feature (Evil Portal, Karma, Beacon spam, Sniffer, Reverse Shell, Scripts, and so on) from the phone.
- From the dashboard, confirm the device card (info, free memory, uptime, battery).
- Try Wardrive: toggle the Wi-Fi AP stream and watch live access points appear, GPS-tagged and mapped on the phone; export to WiGLE CSV, KML or GPX.
- Open the Console command palette to run any Bruce CLI command and see its output.
- Explore the capability-gated pages: Crack (download a wordlist, then crack a captured PMKID/handshake), Monitor (full 802.11 capture to pcap for Wireshark), MITM (ARP redirect plus the on-phone HTTPS proxy), the Spam hub (Apple / Android / Windows / Samsung), Sub-GHz, NFC, IR, BLE and the Tools.
- Generate a session Report with OSINT and insights when you are done.
- Check the Updates screen to update the app (OTA) and flash the device firmware over USB from inside the app.
- Explore the rest in Features.
The device stays a full Bruce when no phone is attached: companion mode is additive, so nothing standalone is lost.