Repository navigation
Building
How to build the firmware and the Android app, sign release builds, and run the host-side protocol tools. See Contributing for project rules and Architecture for where things live.
| Path | What |
|---|---|
| (root) | Fork of the Bruce firmware (AGPL): src/, platformio.ini, boards. Companion code in src/companion/. |
android/ |
Native Android app (Kotlin + Jetpack Compose), package app.brucia. |
proto/ |
The companion wire protocol - the single source of truth for both sides. |
docs/ |
Usage, comparison, hardware proof, and the browser flasher (GitHub Pages). |
tools/ |
Host-side protocol clients (companion_test.py, mock device, e2e). |
PlatformIO with the pioarduino core (a Python 3.11 venv is recommended). The target
environment is lilygo-t-embed-cc1101.
pio run -e lilygo-t-embed-cc1101 # build
pio run -e lilygo-t-embed-cc1101 -t upload # flash over USBA merged, flashable image is produced at
.pio/build/lilygo-t-embed-cc1101/firmware.factory.bin - this is what the browser
flasher at https://1vcian.me/Brucia/ serves.
Notes:
- The board is an ESP32-S3 with native USB CDC; no external USB-serial adapter is needed.
- Partition layout comes from the
custom_*.csvfiles. - Firmware additions such as deauth, battery reporting and lite mode require flashing the latest build.
JDK 17 or newer is required (21 and 23 are tested).
cd android
./gradlew :app:testDebugUnitTest # unit + Paparazzi screenshot tests
./gradlew :app:assembleDebug # debug APK
./gradlew :app:recordPaparazziDebug # re-record UI snapshots after a UI changeThe debug APK is produced under android/app/build/outputs/apk/.
Release builds are signed from a keystore that is never committed. Create
android/keystore.properties (git-ignored) with:
storeFile=/absolute/path/to/brucia.keystore
storePassword=...
keyAlias=brucia
keyPassword=...
Then build the signed release:
cd android
./gradlew :app:assembleReleaseWithout that file, the release build falls back to unsigned, so CI and fresh clones still build.
Useful for testing the companion protocol without the app. On the device, tap Brucia on the home screen to enter companion mode first (for the live tests).
# Handshake + PING against a real device
python3 tools/companion_test.py /dev/tty.usbmodemXXXX
# Live Wi-Fi AP stream from a real device
python3 tools/companion_test.py /dev/tty.usbmodemXXXX --wardrive
# Mock-device end-to-end protocol test (no hardware)
python3 tools/test_protocol_e2e.pytools/ also includes mock_device.py (a software device that speaks the protocol)
and gen_mfcodes.py.
CI runs the firmware build, the Android unit and Paparazzi screenshot tests, and the protocol end-to-end test. Gate commits on a green build and tests.