|
1 | 1 |  |
2 | 2 |
|
3 | | -# :shark: Bruce |
| 3 | +# Bruce Custom Firmware — Enhanced App Platform |
4 | 4 |
|
5 | | -Bruce is a versatile ESP32 firmware that supports a ton of offensive features focusing on facilitating Red Team operations. |
6 | | -It also supports M5stack and Lilygo products and works great with Cardputer, Sticks, M5Cores, T-Decks and T-Embeds. |
| 5 | +A custom fork of the [Bruce firmware](https://github.com/BruceDevices/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. |
7 | 6 |
|
8 | | -**Check our fully open-source hardware too:** https://bruce.computer/boards |
| 7 | +> **Original Bruce firmware:** https://github.com/BruceDevices/firmware |
| 8 | +> |
| 9 | +> **All credit for the base firmware goes to the [Bruce team and contributors](https://github.com/BruceDevices/firmware/graphs/contributors).** This fork builds on top of their work. |
9 | 10 |
|
10 | | -## :building_construction: How to install |
| 11 | +--- |
11 | 12 |
|
12 | | -### The easiest way to install Bruce is using our official Web Flasher! |
13 | | -### Check out: https://bruce.computer/flasher |
| 13 | +## What's New in This Fork |
14 | 14 |
|
15 | | -Alternatively, you can download the latest binary from releases or actions and flash locally using esptool.py |
16 | | -```sh |
17 | | -esptool.py --port /dev/ttyACM0 write_flash 0x00000 Bruce-<device>.bin |
| 15 | +### Apps Menu |
| 16 | +- New **Apps** menu in the main menu |
| 17 | +- Automatically discovers apps from the `/apps/` directory on SD card or LittleFS |
| 18 | +- Each app uses a `manifest.json` to define its name, version, category, and entry point |
| 19 | +- Launch apps directly from the menu |
| 20 | + |
| 21 | +### Memory Improvements |
| 22 | +- JS interpreter heap increased from 64KB to **512KB** using PSRAM (with automatic fallback) |
| 23 | +- Task stack size increased from 8KB to **16KB** for more complex scripts |
| 24 | + |
| 25 | +### New JavaScript API Modules |
| 26 | + |
| 27 | +**BLE (`ble` module)** |
| 28 | +- `ble.scan(duration)` — Scan for nearby BLE devices, returns array of results |
| 29 | +- `ble.advertise(name, duration)` — Broadcast as a BLE device |
| 30 | + |
| 31 | +**NRF24 (`nrf24` module)** |
| 32 | +- `nrf24.begin(cePin, csnPin)` — Initialize the RF24 radio |
| 33 | +- `nrf24.setChannel(ch)` — Set RF channel (0–125) |
| 34 | +- `nrf24.openReadPipe(pipe, address)` / `nrf24.openWritePipe(address)` |
| 35 | +- `nrf24.startListening()` / `nrf24.stopListening()` |
| 36 | +- `nrf24.available()` / `nrf24.read(length)` / `nrf24.write(data)` |
| 37 | + |
| 38 | +**LED (`led` module)** |
| 39 | +- `led.setColor(r, g, b)` — Set RGB LED color |
| 40 | +- `led.setBrightness(value)` — Set brightness (0–255) |
| 41 | +- `led.off()` — Turn LED off |
| 42 | +- `led.blink(delay_ms)` — Blink once |
| 43 | + |
| 44 | +**Menu (`menu` module)** |
| 45 | +- `menu.show(title, options)` — Display a native Bruce menu, returns selected index |
| 46 | +- `menu.alert(title, message)` — Show an alert dialog |
| 47 | +- `menu.confirm(title, message)` — Show yes/no confirmation, returns boolean |
| 48 | + |
| 49 | +--- |
| 50 | + |
| 51 | +## Creating an App |
| 52 | + |
| 53 | +1. Create a folder on your SD card under `/apps/`, e.g. `/apps/my_app/` |
| 54 | +2. Add a `manifest.json`: |
| 55 | + |
| 56 | +```json |
| 57 | +{ |
| 58 | + "name": "My App", |
| 59 | + "description": "What my app does", |
| 60 | + "entry": "main.js", |
| 61 | + "category": "Tools", |
| 62 | + "version": "1.0" |
| 63 | +} |
18 | 64 | ``` |
19 | 65 |
|
20 | | -**For m5stack devices** |
| 66 | +3. Add your `main.js` script (or whatever you named the entry point) |
| 67 | + |
| 68 | +### Example App |
21 | 69 |
|
22 | | -If you already use M5Launcher to manage your m5stack device, you can install it with OTA |
| 70 | +```javascript |
| 71 | +// /apps/led_demo/main.js |
| 72 | +led.setColor(255, 0, 0); |
| 73 | +led.setBrightness(128); |
| 74 | + |
| 75 | +var choice = menu.show("LED Demo", ["Red", "Green", "Blue", "Off"]); |
| 76 | +if (choice === 0) led.setColor(255, 0, 0); |
| 77 | +else if (choice === 1) led.setColor(0, 255, 0); |
| 78 | +else if (choice === 2) led.setColor(0, 0, 255); |
| 79 | +else led.off(); |
| 80 | +``` |
23 | 81 |
|
24 | | -Or you can burn it directly from the [m5burner tool](https://docs.m5stack.com/en/download), just search for 'Bruce' (My official builds will be uploaded by "owner" and have photos.) on the device category you want to and click on burn |
| 82 | +--- |
25 | 83 |
|
| 84 | +## Flashing |
| 85 | + |
| 86 | +Put your T-Embed CC1101 into bootloader mode (hold **BOOT**, press **RESET**, release **BOOT**), then: |
| 87 | + |
| 88 | +```sh |
| 89 | +esptool.py --chip esp32s3 --port COMx write_flash 0x0 Bruce-lilygo-t-embed-cc1101.bin |
| 90 | +``` |
26 | 91 |
|
27 | | -## :keyboard: Discord Server |
| 92 | +Replace `COMx` with your actual COM port. |
28 | 93 |
|
29 | | -Contact us in our [Discord Server](https://discord.gg/WJ9XF9czVT)! |
| 94 | +--- |
30 | 95 |
|
31 | | -## :bookmark_tabs: Wiki |
| 96 | +## Original Bruce Features |
32 | 97 |
|
33 | | -For more information on each function supported by Bruce, [read our wiki here](https://github.com/pr3y/Bruce/wiki). |
34 | | -Also, [read our FAQ](https://github.com/pr3y/Bruce/wiki/FAQ) |
| 98 | +This fork includes **all** features from the original Bruce firmware. See the [original README](https://github.com/BruceDevices/firmware) for the full feature list, including: |
35 | 99 |
|
36 | 100 | ## :computer: List of Features |
37 | 101 |
|
|
0 commit comments