commit b3026f16d7b3ca7da3822d28a2bc77775b88ce2d Author: drjones Date: Wed Apr 15 22:22:29 2026 -0700 first commit Made-with: Cursor diff --git a/README.md b/README.md new file mode 100644 index 0000000..7d16143 --- /dev/null +++ b/README.md @@ -0,0 +1,155 @@ +# nRF24 Jammer — ESP32-S3 Edition + +**Two Nordic radios. One ESP32-S3. A full control plane in your browser.** + +This firmware turns a dual **nRF24L01+** setup into a configurable 2.4 GHz test platform driven by an **ESP32-S3**: Wi-Fi access point, embedded web UI, live dashboard, JSON status API, browser-based OTA, and a serial command shell. Jamming runs on a dedicated FreeRTOS task so the web stack stays responsive while the radios do their job. + +> **Upstream lineage:** Based on the community [nRF24_jammer](https://github.com/W0rthlessS0ul/nRF24_jammer) project, extended and tuned for ESP32-S3. + +--- + +## The feature stack + +| Layer | What you get | +|--------|----------------| +| **Radios** | Two **RF24** modules on a shared **HSPI** bus (16 MHz SPI), independent CE lines, PA cranked up, 2 Mbps, ACK off — built for aggressive channel work. | +| **Jam profiles** | **Bluetooth**, **drone**, **Wi‑Fi** (all channels or one channel), **BLE**, **Zigbee**, and **misc** (custom nRF24 channel range **0–125**). | +| **Methods** | **Carrier** (constant carrier / channel sweeping) vs **packet** (`writeFast` floods) depending on mode and settings. | +| **Topology** | **Split** radios on different channels vs **locked** on the same channel — EEPROM‑persisted (`Separate_or_together`). | +| **Control** | Web UI routes for each mode, **settings** pages, **Wi‑Fi AP credentials**, **OTA** upload with progress, **`/status`** JSON, **`/dashboard`** visualization. | +| **Shell** | **115200** baud serial: `help`, `jam …`, `miscjam …`, `stop`, `setting …`, `info`, `reboot`. | +| **Persistence** | **EEPROM** stores jam methods and AP SSID/password (survives power cycles). | + +--- + +## Hardware you need + +- **ESP32-S3** dev board (USB‑programmable). +- **Two nRF24L01+** modules (with regulators/decoupling as usual — noisy power = flaky RF). +- Wiring per `options.cpp` / SPI init in `jam.cpp`: + +| Signal | ESP32-S3 GPIO | Notes | +|--------|----------------|--------| +| **HSPI SCK** | **12** | Shared bus | +| **HSPI MISO** | **13** | | +| **HSPI MOSI** | **11** | | +| **Radio A CE** | **5** | `RF24 radio(5, 17, …)` | +| **Radio A CSN** | **17** | | +| **Radio B CE** | **16** | `RF24 radio1(16, 4, …)` | +| **Radio B CSN** | **4** | | + +3.3 V logic and clean ground returns between ESP32 and both nRF24 boards are non‑negotiable if you want stable runs. + +--- + +## Flashing the firmware (Arduino IDE) + +1. **Install board support** + In Arduino IDE → *Preferences* → *Additional boards manager URLs*, add: + + `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json` + + Then *Tools → Board → Boards Manager* → install **esp32** by Espressif. + +2. **Pick the right board** + *Tools → Board* → choose the **ESP32-S3** entry that matches **your** module (DevKit, WROOM, N16R8, etc.). + If your module uses **octal flash/PSRAM** (common on some S3 modules), set **Flash mode** / **PSRAM** per your board vendor — wrong flash mode often shows up as boot loops or failed uploads. + +3. **Port & upload** + Select the correct **COM** / **USB** port, open this sketch folder (`nRF24_jammer_ESP32S3.ino`), click **Upload**. + Some S3 boards need a **manual reset** or **boot** button sequence after upload — if the port disappears or the sketch doesn’t start, check your board’s docs. + +4. **Libraries** + This repo ships vendored libs under `lib/` (**RF24**, **Adafruit_GFX**, **Adafruit_SSD1306**, **Adafruit_BusIO**, **GyverButton**). Point Arduino’s library path at `lib` or symlink/copy as you prefer so the build finds them. + +--- + +## First boot: get in + +| Item | Default (see `options.cpp`) | +|------|-----------------------------| +| **SoftAP SSID** | `temple` | +| **SoftAP password** | `password` | +| **Typical AP IP** | `http://192.168.4.1` (ESP32 default soft-AP address) | + +Connect to that Wi‑Fi network from a laptop or phone, then open the IP in a browser. + +**Serial:** open a terminal at **115200** baud — you’ll see the ASCII banner and pointers to `help`, the AP IP, and `/dashboard`. + +--- + +## Web UI map (quick reference) + +| Path | Purpose | +|------|---------| +| **`/`** | Main control page | +| **`/bluetooth_jam`**, **`/drone_jam`**, **`/wifi_jam`**, **`/ble_jam`**, **`/zigbee_jam`** | Start the named profile | +| **`/misc_jammer`** → **`/misc_jam?start=&stop=`** | Sweep **nRF24 channels** in a range | +| **`/wifi_selected_jam`** / **`/wifi_select`**, **`/wifi_channel`** | Wi‑Fi‑focused selection | +| **`/setting_*`** | Per‑mode settings, separate/together, misc method | +| **`/wifi_settings`**, **`/save_wifi_settings`**, **`/reset_wifi_settings`** | Change AP SSID/password (reboot after save) | +| **`/OTA`** | Over‑the‑air firmware update UI | +| **`/update`** (POST) | OTA upload endpoint | +| **`/status`** | JSON: channels, loop count, uptime, mode, carrier vs packet | +| **`/dashboard`** | Live view fed by status data | + +Jamming does **not** auto‑start on boot — bring the radios online, then start a mode from the UI or serial. + +--- + +## Serial cheat sheet + +``` +help +jam bluetooth | drone | ble | zigbee +jam wifi all +jam wifi <0-13> +miscjam # nRF24 channels 0-125 +stop +setting # lists EEPROM-backed options +setting +info +reboot +``` + +`setting` names match the firmware: `BluetoothJamMethod`, `DroneJamMethod`, `MiscJamMethod`, `JammingType`, etc. (see `serial.cpp`). + +--- + +## OTA updates + +1. Browse to **`/OTA`** on the device. +2. Upload a compiled **`.bin`** built for the **same** partition layout and board target as USB flashes. +3. Wait for success — the device reboots into the new image. + +Watch the serial log if something fails; OTA is picky about image size and partition tables. + +--- + +## Troubleshooting + +| Symptom | Check | +|---------|--------| +| Upload fails / board not in bootloader | USB cable, drivers, correct **COM** port, boot/reset combo for your S3 board. | +| Boot loop after flash | **Flash mode** / **PSRAM** / **USB CDC** settings vs your module. | +| Web UI unreachable | Connected to the **jammer AP**? Correct IP? Firewall on client? | +| Radios “dead” | 3.3 V, wiring, CE/CSN pins, shared SPI wiring, power supply noise. | +| Settings forgotten | EEPROM size/commit; avoid cutting power mid-write. | + +--- + +## Legal & safety — read this + +Intentional interference with licensed radio services is **illegal in many countries** and can carry civil and criminal penalties. This firmware is provided for **education**, **authorized RF testing in shielded labs**, and **understanding how 2.4 GHz stacks behave** — **not** for disrupting Wi‑Fi, drones, Bluetooth, or any other service you do not own or have explicit permission to test. + +**You** are responsible for compliance with local law, spectrum rules, and institutional policy. If you cannot use it legally, **do not run it**. + +--- + +## License / credits + +Project structure and behavior trace back to open-source nRF24 jammer work; see the banner in `serial.cpp` for the original GitHub link. Respect upstream licenses if you redistribute. + +--- + +*Built for people who read datasheets for fun — keep it in the lab, keep it legal, and keep the smoke inside the silicon.*