# 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 <start> <end>     # nRF24 channels 0-125
stop
setting                   # lists EEPROM-backed options
setting <name> <value>
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.*