Roxanne

you don’t have to put on the red light, because this firmware will do it for you

One‑sentence summary: ESP32 firmware that scans for known unauthenticated BLE lighting protocols and tries to set matched lights to red for interoperability/security validation.

Overview / Motivation

Roxanne is a focused ESP‑IDF firmware project for ESP32 boards (including 18650 sled WeMos boards) that scans for BLE lights using known, unauthenticated control protocols. When a device matches a supported signature, the firmware attempts a single GATT write to set the light to red. The goal is to validate interoperability and highlight exposure of unauthenticated BLE lighting protocols—without brute‑forcing or fuzzing.

Features

• Scans for nearby BLE lighting devices with known unauthenticated protocols
• Matches protocols, then applies optional name/MAC/service UUID gates
• Performs a single red color write per matched device, then disconnects
• One‑shot per device (tracked in memory to avoid repeat attempts)
• Safety gates via whitelist name/MAC/service UUID checks
• Clean serial logging for test/validation workflows

Hardware Requirements

• ESP32 development board with BLE support
  • Example: 18650 sled WeMos boards, TTGO‑style boards, or similar
• USB cable for flashing and serial output
• Optional: 18650 Li‑ion cell (if your board supports it)

Dependencies

• ESP‑IDF v5.x (recommended) or compatible version configured for your ESP32
• idf.py toolchain installed and available in your environment
• Python 3.8+

Installation

1. Set up ESP‑IDF

   • Follow the official ESP‑IDF getting started guide for your platform.

2. Clone the repo

   git clone https://github.com/<your-org>/roxanne.git
   cd roxanne

3. Configure and build

   idf.py set-target esp32
   idf.py menuconfig
   idf.py build

4. Flash and monitor

   idf.py -p /dev/ttyUSB0 flash monitor

Usage

1. Power the ESP32 or reset it.
2. The firmware scans for BLE advertisements and logs matches.
3. For each matched device, Roxanne connects once, writes a red color command, and disconnects.

Interpreting Output

• Look for match logs that indicate a recognized protocol.
• Write success/failure indicates whether the red command was accepted.
• Devices are tracked to avoid repeated writes.

Test Modes

Optional gates can be enabled to reduce risk:

• Name prefix whitelist (disabled by default)
• MAC whitelist
• Service UUID test mode
• Safety gate checks (the combined name/MAC/service UUID gates; all enabled checks must pass before connecting)

These are configured in main/config.h.

Protocol Support List

Current modules target common BLE lighting protocols:

• Triones / HappyLighting / LEDBLE
• Magic Blue
• MiPow Playbulb
• ELK‑BLEDOM
• Govee BLE
• Nordic LED demo

ESP-NOW Support

Roxanne also broadcasts red color commands to WLED devices over ESP-NOW. This uses unauthenticated, broadcast-only packets and does not require any Wi-Fi association or pairing. Target MAC addresses can be hardcoded or discovered via scan, and the ESP-NOW broadcast runs in parallel with existing BLE control.

Contributing

Contributions are welcome!

• Currently, this project lacks real-world testing, bug reports are always welcome.
• Open an issue for discussion before large changes.
• Submit a PR with clear motivation and testing notes.

Running Tests

There is no dedicated test harness yet, but you can validate behavior via:

idf.py build
idf.py flash monitor

Consider adding unit tests under main/ if you introduce protocol parsing logic.

Example Serial Output

I (1283) roxanne: roxanne ble interop validator start
I (2337) roxanne: scan start
I (2451) roxanne: match AA:BB:CC:DD:EE:FF -> ELK-BLEDOM RSSI -62
I (3012) roxanne: connected AA:BB:CC:DD:EE:FF
I (3090) elk_bledom: sending red command
I (3402) roxanne: write complete AA:BB:CC:DD:EE:FF status=0 time=3402
I (3560) roxanne: disconnected AA:BB:CC:DD:EE:FF reason=19