156 lines
7.1 KiB
Markdown
156 lines
7.1 KiB
Markdown
# 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.*
|