first commit
Made-with: Cursor
This commit is contained in:
drjones
155
README.md
Normal file
155
README.md
Normal file
@@ -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 <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.*
|
||||
Reference in New Issue
Block a user