first commit

Made-with: Cursor

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 <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.*