Add MIT License

Made-with: Cursor

.editorconfig

@@ -0,0 +1,17 @@
+# EditorConfig is awesome: https://editorconfig.org
+<!-- stewardship-standard: editorconfig-v1 -->
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

.gitattributes

@@ -0,0 +1,27 @@
+# stewardship-standard: gitattributes-v1
+* text=auto eol=lf
+
+*.md text eol=lf
+*.txt text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.sh text eol=lf
+*.py text eol=lf
+*.js text eol=lf
+*.ts text eol=lf
+*.c text eol=lf
+*.cpp text eol=lf
+*.h text eol=lf
+*.hpp text eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.pdf binary
+*.zip binary
+*.bin binary
+*.elf binary
+*.uf2 binary

.gitea/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+# Bug Report
+
+## Summary
+
+Describe the problem and expected behavior.
+
+## Environment
+
+- Repo version/commit:
+- OS/toolchain/board/service:
+- Relevant configuration with secrets removed:
+
+## Reproduction
+
+1.
+2.
+3.
+
+## Logs
+
+Paste only sanitized logs. Remove credentials, tokens, personal data, captures, dumps, and target identifiers.

.gitea/ISSUE_TEMPLATE/docs_task.md

@@ -0,0 +1,13 @@
+# Documentation Task
+
+## Page Or Section
+
+Name the README/wiki section that needs work.
+
+## Change Needed
+
+Describe what should be clearer, corrected, or added.
+
+## Source Of Truth
+
+Link to code, hardware notes, upstream docs, release notes, or maintainer decision.

.gitea/ISSUE_TEMPLATE/release_checklist.md

@@ -0,0 +1,14 @@
+# Release Checklist
+
+## Scope
+
+Describe what is being released and why.
+
+## Checks
+
+- [ ] README and wiki are current.
+- [ ] Changelog entry exists.
+- [ ] License/provenance is clear.
+- [ ] No secrets or private data are included.
+- [ ] Firmware/binary artifacts include SHA256 hashes and target details.
+- [ ] Build or smoke-check result is recorded.

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+# Pull Request Checklist
+
+- [ ] Scope is clear and limited.
+- [ ] README/wiki updates are included when behavior, setup, hardware, or release process changes.
+- [ ] No secrets, tokens, private data, dumps, captures, or generated dependency folders are committed.
+- [ ] Build/test/smoke-check result is documented.
+- [ ] License or upstream provenance is preserved.

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All meaningful changes to this repository should be recorded here.
+
+## Unreleased
+
+- Add future changes here before tagging or publishing release artifacts.
+
+## 2026-05-20 - Gitea Stewardship Import
+
+- Verified README and wiki coverage.
+- Added standard stewardship documentation where missing.
+- Established security, contribution, release, and provenance expectations.

CODEOWNERS

@@ -0,0 +1 @@
+* @drjones

CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+## Maintainer Expectations
+
+Keep changes small, reviewable, and tied to a clear project purpose. Do not mix source changes with generated build output or dependency caches.
+
+## Before Committing
+
+- Run the relevant build, lint, or smoke test when the project provides one.
+- Check that no credentials, `.env` files, tokens, private keys, captures, dumps, or personal data are staged.
+- Keep firmware binaries, large archives, and generated artifacts out of Git unless the repo explicitly documents otherwise.
+- Preserve upstream licenses and attribution for third-party code.
+
+## Documentation
+
+Update README and wiki pages when setup, hardware, architecture, environment variables, or release behavior changes.
+
+## Safety
+
+Only submit work intended for authorized environments. Project documentation should make scope and safe operation clearer, never weaker.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sudo-jones-cmd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE_STATUS.md

@@ -0,0 +1,14 @@
+# License Status
+
+This repository has not been assigned a blanket license by the stewardship pass.
+
+## Current Rule
+
+- Existing upstream licenses must be preserved.
+- Third-party code must retain attribution and license files.
+- Original private work remains all rights reserved until an explicit license is selected.
+- Do not assume MIT, Apache, GPL, or public-domain status unless a license file in this repository says so.
+
+## Next Step
+
+Classify ownership and dependencies before publishing releases or accepting external contributions.

README.md

@@ -7,29 +7,22 @@ ESP32-S3 + dual CC1101 + external amplifiers + OLED display + web interface.
 
 ## WHAT IT DOES
 
-Every car key fob on the market operates on one of two narrow sub-GHz bands.
+Most car key fobs that matter for NA vs EU/global boil down to two on-air
-This device sweeps both bands simultaneously with continuous FM noise, leaving
+channels: about **315 MHz** (North America) and **433.92 MHz** (Europe and much
-zero gaps between hops and zero time for a fob transmission to get through.
+of the rest of the world).
 
-    300 - 320 MHz   North American band
+This firmware **does not sweep** those bands anymore. Each CC1101 **locks** on
-                    Honda/Acura 303.825 MHz
+one frequency and stays there at full configured TX power:
-                    Chamberlain/LiftMaster 310.0 MHz
-                    Toyota/Lexus/Scion 314.98 MHz
-                    Ford/GM/Chrysler/Dodge/Jeep 315.0 MHz
-                    Linear Delta-3 / LiftMaster 318.0 MHz
 
-    390 - 436 MHz   European and global band
+    Radio 1   315.000 MHz    Narrow FM deviation + Galois LFSR on GDO0
-                    Chamberlain/LiftMaster 390.0 MHz
+                              (energy concentrated on the NA fob channel)
-                    Holtek-based remotes 418.0 MHz
-                    Somfy RTS / SMC 5326 433.42 MHz
-                    BMW/VW/Audi/Mercedes/Hyundai/Kia 433.92 MHz
-                    Asian/Euro fobs 434.42 MHz
 
-A fob button press generates a 200-500ms transmission window.
+    Radio 2   433.920 MHz    Maximum CC1101 FM deviation + same LFSR
-Radio 1 completes a full sweep of 300-320 MHz every 75ms.
+                              (wide, loud noise on the dominant EU/global ISM fob channel)
-Radio 2 completes a full sweep of 390-436 MHz every 180ms.
+
-Every target frequency gets hit multiple times per fob press.
+Both antennas scream continuously while jamming is enabled — no hopping, no
-The car never receives a clean signal.
+dwell time, no split energy across a span. The web UI and OLED show these as
+locked carriers (`jam_fixed` in telemetry).
 
 ---
 
@@ -57,17 +50,17 @@ The car never receives a clean signal.
     GPIO 12   SCK
     GPIO 13   MISO
 
-    [CC1101 NUMBER 1 - 300-320 MHz sweep]
+    [CC1101 NUMBER 1 - 315 MHz locked jam]
 
     GPIO  7   CS   (chip select, dedicated)
-    GPIO  4   GDO0 (LEDC PWM noise output)
+    GPIO  4   GDO0 (LFSR noise into direct async TX)
     3V3       VCC
     GND       GND
 
-    [CC1101 NUMBER 2 - 390-436 MHz sweep]
+    [CC1101 NUMBER 2 - 433.92 MHz locked jam]
 
     GPIO  8   CS   (chip select, dedicated)
-    GPIO  5   GDO0 (LEDC PWM noise output)
+    GPIO  5   GDO0 (LFSR noise into direct async TX)
     3V3       VCC
     GND       GND
 
@@ -97,33 +90,24 @@ The car never receives a clean signal.
 
     [RF CONFIGURATION]
 
-    Modulation         FM noise (direct async TX via GDO0 LEDC PWM)
+    Carrier plan         Radio 1 locked 315.000 MHz, Radio 2 locked 433.920 MHz
-    Frequency deviation  380 kHz (CC1101 hardware maximum)
+    Modulation           FM from Galois LFSR bitstream on GDO0 (direct async TX)
-    Noise bandwidth      ~1010 kHz per hop (Carson rule: 2 x (380 + 125))
+    Deviation R1         25 kHz (narrow — energy on 315)
-    Bitrate              250 kbps
+    Deviation R2         380 kHz (CC1101 max — wide noise on 433.92)
+    LFSR clock           50 kHz (hardware timer ISR)
+    Bitrate (RadioLib)   250 kbps context for begin()
     RX bandwidth         812 kHz (maximum)
     TX power             -30 / -20 / -15 / -10 / 0 / 5 / 7 / 10 dBm (8 steps)
     Default TX power     10 dBm
     Amplifier gain       +20 dB (configurable in web UI)
     Effective output     30 dBm / ~1 Watt (with amplifiers, at 10 dBm TX)
 
-    [SWEEP CONFIGURATION - defaults]
+    [LEGACY SWEEP SETTINGS IN WEB UI / NVS]
 
-    Radio 1 center       310.0 MHz
+    Dwell, steps, and span are still saved to NVS if you use Apply Sweep.
-    Radio 1 span         20.0 MHz  (300 - 320 MHz)
+    Fixed-carrier jamming does not use them. Tunables are in config.h:
-    Radio 1 steps        25        (0.83 MHz spacing, within 1 MHz hop width)
+    JAM_LOCK_FREQ_1_MHZ, JAM_LOCK_FREQ_2_MHZ, JAM_DEV_KHZ_R1_NARROW,
-    Radio 1 cycle time   75 ms     (25 steps x 3ms dwell)
+    JAM_DEV_KHZ_R2_WIDE.
-
-    Radio 2 center       413.0 MHz
-    Radio 2 span         46.0 MHz  (390 - 436 MHz)
-    Radio 2 steps        60        (0.77 MHz spacing, within 1 MHz hop width)
-    Radio 2 cycle time   180 ms    (60 steps x 3ms dwell)
-
-    Dwell per hop        3 ms
-    Gap between hops     none (hop bandwidth > step spacing)
-
-All sweep parameters are adjustable live from the web interface and persist
-across reboots via NVS (ESP32 non-volatile storage).
 
 ---
 
@@ -136,11 +120,11 @@ Three dot indicators in the header show the current page.
 
     [PAGE 0 - STATUS]  (default)
 
-    Header:  inverted bar reading JAMMING ACTIVE when running, STANDBY when not
+    Header:  inverted bar reading LOCKED JAM when running, STANDBY when not
     Row 1:   ANT1 current frequency in MHz with animated radio-wave arcs
     Row 2:   ANT2 current frequency in MHz with animated radio-wave arcs
     Row 3:   TX power breakdown: radio dBm + amp gain = effective dBm
-    Row 4:   FULL DUAL-BAND TX badge when both radios active, else temp and heap
+    Row 4:   315 + 433.92 LOCK badge when both radios active, else temp and heap
     Row 5:   uptime since boot
 
     [PAGE 1 - FREQ AND HOPS]
@@ -219,25 +203,20 @@ Connect to the WiFi access point, then open the control panel in a browser.
     Start / Stop jamming toggle
     TX power selector (8 levels: -30 dBm to 10 dBm)
     Amplifier gain input (dB, affects displayed effective power only)
-    Sweep dwell time (ms per hop)
+    Sweep tuning fields (legacy — stored in NVS only, not used for jam)
-    Radio 1 steps and span (MHz)
-    Radio 2 steps and span (MHz)
     All settings persist to NVS on save
 
     [VISUALIZATIONS]
 
-    Two canvas sweep displays, one per radio band.
+    Two canvas displays show a narrow window around each locked carrier (markers
-    Each shows the sweep range with named frequency markers:
+    for common fob channels still drawn where they fall in range).
-        315 MHz band: Honda, Toyota, LiftMaster, Ford/GM markers
-        433 MHz band: LiftMaster 390, Holtek 418, Somfy, BMW/VW/Audi markers
-    Current hop position shown with a heat trail fading over recent positions.
     Canvas height 90px, updates every 1 second with telemetry.
 
     Two sparkline charts showing 2-minute rolling history:
         Temperature (Celsius)
         Free heap (KB)
 
-    [METRICS GRID - 12 stats updated every 1 second]
+    [METRICS GRID - stats updated every 1 second]
 
     Effective TX power (dBm)
     Radio 1 status
@@ -247,8 +226,10 @@ Connect to the WiFi access point, then open the control panel in a browser.
     Minimum heap KB recorded
     Hop count Radio 1 (total since boot)
     Hop count Radio 2 (total since boot)
-    Combined hops per second
+    Hop counters (stay at 0 in fixed-carrier mode; kept for API compatibility)
     WiFi clients on AP
+    Nodes (ESP-NOW): count of other boards running this firmware in range
+    Jam mode: LOCKED when jam_fixed is true in telemetry
     Uptime
     24-hour mission progress bar in the header
 
@@ -262,6 +243,32 @@ Connect to the WiFi access point, then open the control panel in a browser.
 
 ---
 
+## ESP-NOW NODE MESH
+
+    Multiple boards running the same firmware discover each other automatically
+    over ESP-NOW. No MAC address entry and no pairing step.
+
+    How it works:
+        Each unit broadcasts a small beacon every 750 ms to the ESP-NOW
+        broadcast address. The payload starts with a fixed magic signature
+        so only this firmware is counted.
+        When a unit hears a valid beacon, it records the sender MAC and
+        refreshes a last-seen time. The web UI metric "Nodes (ESP-NOW)" is
+        the number of other units heard within the last 12 seconds.
+        The OLED health page shows the same count after "ESPNOW".
+
+    Requirements for links to work:
+        All units must share the same Wi-Fi radio channel as the soft-AP.
+        This build starts the AP on channel 1. Do not run different channel
+        settings on different boards unless you change the code consistently.
+        Range is typical 2.4 GHz ESP-NOW range (often tens of meters indoors,
+        more line-of-sight).
+
+    Note: This release only counts peers and logs new MACs. It does not yet
+    sync jamming state or share telemetry over ESP-NOW.
+
+---
+
 ## RELIABILITY FEATURES (24-HOUR OPERATION)
 
 The system is designed to run unattended at full power indefinitely.
@@ -322,8 +329,7 @@ The system is designed to run unattended at full power indefinitely.
 
     [KEY FUNCTIONS IN MAIN.CPP]
 
-    startJamming()          initializes both CC1101s, sets power, starts async TX
+    startJamming()          initializes both CC1101s, locks freqs, sets deviation, async TX
-    tickSweep()             advances one radio by one hop step
     oledTick()              OLED update loop, handles pages and notifications
     oledDrawStatus()        page 0 renderer
     oledDrawFreq()          page 1 renderer
@@ -332,19 +338,16 @@ The system is designed to run unattended at full power indefinitely.
     oledBootMsg()           synchronous boot status message
     encISR()                rotary encoder interrupt service routine
     handleToggle()          HTTP handler: start/stop jamming
-    handleSettings()        HTTP handler: update sweep and power parameters
+    handleSettings()        HTTP handler: update TX power
     handleTelemetry()       HTTP handler: JSON status for web UI polling
     handleLogs()            HTTP handler: timestamped log ring buffer
     handleRoot()            HTTP handler: serves embedded web UI HTML
     logLine()               timestamped log entry to ring buffer and Serial
-    loop()                  sweeps both radios, runs OLED, runs OTA, watchdog
+    loop()                  ESP-NOW tick, HTTP, OLED, capture FSM, watchdog
 
-    [SWEEP LOOP TIMING]
+    [JAM TIMING]
 
-    Both radios are swept independently in the same loop() pass.
+    Carriers are fixed after startJamming(); no hop loop. LFSR ISR runs at 50 kHz.
-    tickSweep() is a no-op if less than sweepDwellMs have elapsed.
-    There are no blocking delays in the main loop.
-    OLED and web server run interleaved with no impact on sweep timing.
 
 ---
 

SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Scope
+
+This repository is maintained for authorized, lawful work only. Do not use code, firmware, payloads, scripts, or documentation from this project against systems, accounts, devices, networks, cards, readers, or services you do not own or do not have explicit permission to test.
+
+## Reporting
+
+Report security concerns privately to the maintainer. Do not open public issues containing live credentials, tokens, private captures, card data, target identifiers, exploit chains, or sensitive logs.
+
+## Secrets And Data
+
+- Do not commit `.env` files, API keys, Wi-Fi credentials, session cookies, private keys, dumps, captures, or personal data.
+- Firmware binaries and captured artifacts must include provenance notes and SHA256 hashes before release.
+- Generated dependency folders and build output belong outside Git unless there is a documented reason.
+
+## Maintainer Rule
+
+If a change increases misuse risk, narrows safety boundaries, or weakens provenance, it must be rejected or quarantined until documented.

cypher-pulse-integration-report.md

@@ -0,0 +1,264 @@
+# Cypher Pulse Signal Jamming Mechanism Analysis & Integration Plan
+
+## Executive Summary
+
+This document provides a comprehensive analysis of the **Cypher Pulse** module's signal jamming mechanism, detailing its core principles, interference patterns, and operational parameters. It further presents a step‑by‑step integration plan to adapt this jamming methodology into the existing dual‑CC1101 lab‑instrument architecture, complete with rigorous testing protocols, error‑handling procedures, and validation steps to ensure a flawless, bug‑free implementation.
+
+---
+
+## 1. Cypher Pulse Module Analysis
+
+### 1.1 Core Principles
+
+The Cypher Pulse module is an ESP32‑based interactive signal‑generation tool that uses **two CC1101 sub‑GHz radio modules** (via the ELECHOUSE_CC1101_SRC_DRV libraries) to perform a variety of RF operations, with **signal jamming** as a primary function.
+
+**Jamming Mechanism:**  
+- The jammer operates by continuously transmitting **60‑byte random payloads** on one or both CC1101 radios.  
+- Random data is generated via `random(255)` and sent with `CC1.SendData()` / `CC2.SendData()` in a tight loop while the jamming mode flag (`jammingmode`) is active.  
+- The transmission is **blocking** (no async or DMA) and runs at full radio power (PA setting 10 = +10 dBm).  
+- The module supports **single‑radio jamming** (CC#1 only or CC#2 only) and **dual‑radio simultaneous jamming**.
+
+**Modulation & Frequency:**  
+- Default modulation is **ASK/OOK** (setModulation 2).  
+- Default frequencies are **433.92 MHz** (CC1) and **434.50 MHz** (CC2), but the user can switch among four presets (433.90, 434.00, 434.30, 434.40 MHz) via menu commands.  
+- Other radio parameters (deviation, channel spacing, RX bandwidth, data rate, sync word, etc.) are set to typical values suitable for generic 433 MHz ISM‑band operation.
+
+**Control Interface:**  
+- **OLED menu system** with three buttons (UP, DOWN, SELECT) for mode selection.  
+- **Serial CLI** with commands for fine‑grained parameter adjustment, raw recording/playback, scanning, and RSSI reading.
+
+### 1.2 Interference Patterns
+
+The Cypher Pulse jammer produces **wideband noise‑like interference** by transmitting random bit sequences at a relatively high symbol rate (default 9.6 kBaud). Because the modulation is ASK/OOK, the RF carrier is simply turned on/off according to the random data, generating a **broad spectrum of sidebands** that can overwhelm nearby receivers operating in the same frequency band.
+
+**Key interference characteristics:**  
+- **Spectral footprint:** Energy spreads across the entire configured channel bandwidth (≈812 kHz) and beyond due to the abrupt OOK transitions.  
+- **Temporal pattern:** Continuous transmission with no idle periods, creating a **constant‑duty‑cycle** interference source.  
+- **Dual‑radio effect:** When both radios are active, they transmit identical random data on two slightly separated frequencies (e.g., 433.92 and 434.50 MHz), effectively jamming two discrete channels simultaneously.
+
+### 1.3 Operational Parameters
+
+| Parameter | CC1101 #1 (Default) | CC1101 #2 (Default) |
+|-----------|---------------------|---------------------|
+| Frequency | 433.92 MHz | 434.50 MHz |
+| Modulation | ASK/OOK (2) | ASK/OOK (2) |
+| Deviation | 47.60 kHz | 47.60 kHz |
+| Channel spacing | 199.95 kHz | 199.95 kHz |
+| RX bandwidth | 812.50 kHz | 812.50 kHz |
+| Data rate | 9.6 kBaud | 9.6 kBaud |
+| TX power | +10 dBm (PA=10) | +10 dBm (PA=10) |
+| Sync word | 0xD391 (211,145) | 0xD391 (211,145) |
+| Packet format | Normal mode (0) | Normal mode (0) |
+| CRC | Disabled (0) | Disabled (0) |
+
+**User‑adjustable parameters via menu:**  
+- Frequency presets (433.90, 434.00, 434.30, 434.40 MHz)  
+- Single/dual radio selection  
+- Raw recording/playback buffer size (up to 4096 bytes)  
+- RSSI monitoring  
+
+---
+
+## 2. Main Project Architecture Overview
+
+The target platform is a **dual‑CC1101 lab instrument** built on an ESP32‑S3 DevKitC‑1, using the **RadioLib** library for radio control. The project already implements a sophisticated multi‑mode jamming system with a web‑based UI, OLED display, rotary encoder, and extensive telemetry.
+
+### 2.1 Existing Jamming Modes
+
+The main project defines six jam modes (enum `JamMode`):
+
+1. **DIRECT** – Wide LFSR‑driven async TX (default).  
+2. **PRECISION** – Narrower deviation & lower LFSR rate for focused energy.  
+3. **FLOOD** – Bursty random‑packet transmission (similar to Cypher Pulse).  
+4. **CW** – Unmodulated carrier (continuous wave).  
+5. **PULSE** – Slow square‑wave modulation (spoofs preamble AGC).  
+6. **SPECIAL** – Exact Cypher‑Pulse clone (60‑byte random payload, 10 ms delay, blocking transmit).
+
+### 2.2 Key Configuration Constants (from `config.h`)
+
+| Symbol | Value | Purpose |
+|--------|-------|---------|
+| `JAM_LOCK_FREQ_1_MHZ` | 315.0 MHz | Fixed jam carrier for radio 1 |
+| `JAM_LOCK_FREQ_2_MHZ` | 433.92 MHz | Fixed jam carrier for radio 2 |
+| `JAM_BITRATE_KBPS` | 250.0 kbps | Baseband bit rate |
+| `JAM_FREQ_DEV_KHZ` | 380.0 kHz | Default frequency deviation |
+| `JAM_RX_BW_KHZ` | 812.0 kHz | Receive bandwidth |
+| `JAM_LFSR_KEY_HZ` | 100 kHz | LFSR toggle rate for direct/precision modes |
+| `JAM_PRECISION_LFSR_HZ` | 40 kHz | LFSR rate for precision mode |
+| `JAM_PULSE_HZ` | 2 kHz | Pulse‑mode square‑wave frequency |
+| `JAM_FLOOD_PKT_BYTES` | 64 | Flood‑mode packet size |
+| `JAM_R1_USE_OOK` | 1 | Use ASK/OOK for radio 1 in direct mode |
+
+### 2.3 Hardware Abstraction
+
+- **SPI**: Shared FSPI bus with separate chip‑select pins for each CC1101.  
+- **GDO0**: Used for direct‑async modulation (LFSR, pulse, CW) and packet‑mode timing.  
+- **OLED**: SSD1306 128×64 via software I²C (GPIO 17/18).  
+- **Rotary encoder**: For OLED page navigation.  
+- **Web server**: Serves a real‑time telemetry UI and provides REST API for mode control.
+
+### 2.4 Current Integration Points
+
+The `startJamming()` function selects modulation, deviation, and GDO0 pin mode according to the active `jamMode`. The `jamFloodTick()` function implements the **FLOOD** and **SPECIAL** modes, the latter being a direct adaptation of Cypher Pulse’s random‑packet transmission.
+
+---
+
+## 3. Integration Plan
+
+The goal is to **fully incorporate the Cypher Pulse jamming methodology** into the main project, leveraging its existing infrastructure while adding configurability, robustness, and comprehensive validation.
+
+### 3.1 Phase 1 – Code Analysis & Mapping
+
+1. **Compare ELECHOUSE and RadioLib APIs** – Verify that every Cypher Pulse radio configuration parameter has an equivalent RadioLib setter.
+2. **Extract parameter mapping table** – Match each `CC1.set*()` call in `cc1101initialize()` to the corresponding `radio1.set*()` method.
+3. **Identify missing features** – Cypher Pulse’s frequency presets, single‑radio selection, and raw buffer recording/playback may need to be added to the main project’s UI.
+4. **Analyze timing characteristics** – Measure the actual on‑air timing of Cypher Pulse’s 10 ms delay in SPECIAL mode; ensure the main project’s `jamFloodTick()` reproduces it exactly.
+
+### 3.2 Phase 2 – Implementation
+
+1. **Enhance the SPECIAL jam mode**  
+   - Make the packet size (60 bytes) and inter‑packet delay (10 ms) configurable via `config.h`.  
+   - Allow the user to select which radio(s) are active (CC#1 only, CC#2 only, both).  
+   - Add the four frequency presets (433.90, 434.00, 434.30, 434.40 MHz) as quick‑select options in the web UI.
+
+2. **Add Cypher‑Pulse‑style CLI commands** (optional)  
+   - Extend the existing serial monitor interface with commands like `SETMHZ`, `SETMODULATION`, `SCAN`, `RECRAW`, `PLAYRAW` to maintain backward compatibility with Cypher Pulse power‑users.
+
+3. **Integrate OLED menu items**  
+   - Add a “Cypher Pulse” sub‑menu that mirrors the original button‑driven interface (2X CC JAM, CC#1 JAM, CC#2 JAM, SCAN, etc.).  
+   - Use the existing rotary‑encoder navigation logic to keep the UI consistent.
+
+4. **Unify configuration storage**  
+   - Store Cypher‑Pulse‑specific settings (selected frequency preset, single/dual radio) in the same NVS (`Preferences`) namespace used for jam‑mode and power‑level.
+
+### 3.3 Phase 3 – Testing Protocols
+
+A **three‑layer testing strategy** ensures correctness, performance, and regulatory compliance.
+
+#### 3.3.1 Unit Tests (PlatformIO test framework)
+- **Radio configuration tests** – Verify that each `set*()` call returns `RADIOLIB_ERR_NONE`.  
+- **Parameter bounds tests** – Ensure frequency, deviation, and power values stay within CC1101 datasheet limits.  
+- **Mode‑transition tests** – Confirm that switching between jam modes does not leave the radio in an undefined state.
+
+#### 3.3.2 Integration Tests (Hardware‑in‑the‑loop)
+- **SPI communication integrity** – Use a logic analyzer to verify correct SPI transactions during jam start/stop.  
+- **GDO0 signal verification** – Capture the LFSR/pulse waveform on an oscilloscope; compare with expected frequency and duty cycle.  
+- **Dual‑radio coordination** – Ensure simultaneous transmission on both radios does not cause SPI contention or timing violations.
+
+#### 3.3.3 RF Performance Validation (SDR‑based)
+- **Spectrum analysis** – Use a software‑defined radio (e.g., RTL‑SDR) to measure the occupied bandwidth, center frequency accuracy, and out‑of‑band emissions for each jam mode.  
+- **Power measurement** – Confirm radiated power matches the configured +10 dBm (within antenna and path‑loss tolerances).  
+- **Interference pattern verification** – Record the on‑air signal of the SPECIAL mode and compare it with the original Cypher Pulse output; ensure the 10 ms periodicity and random‑payload characteristics match.
+
+### 3.4 Phase 4 – Error Handling & Safeguards
+
+1. **Radio initialization watchdog** – If a CC1101 fails to respond after three SRES attempts, mark it as faulty and continue with the remaining radio (single‑radio fallback).  
+2. **Thermal monitoring** – Read the ESP32‑S3 internal temperature sensor; throttle TX duty cycle or temporarily stop jamming if the chip exceeds 85 °C.  
+3. **SPI bus lock‑up detection** – Implement a timeout on SPI transactions; trigger a full bus reset (toggle CS lines) if a transaction hangs longer than 100 ms.  
+4. **Heap exhaustion guard** – Monitor free heap size; if it drops below 20 KB, log a warning and avoid dynamic memory allocations in the jam‑tick loop.  
+5. **User‑visible fault indicators** – Show “RADIO FAULT” on the OLED and web UI, with a detailed error message available via the serial log.
+
+### 3.5 Phase 5 – Validation & Deployment
+
+1. **Continuous integration** – Add a GitHub Actions workflow that runs the unit tests on every commit and blocks merging if any test fails.  
+2. **Pre‑release checklist** –  
+   - [ ] All six jam modes operate correctly on both radios.  
+   - [ ] Frequency presets switch without glitches.  
+   - [ ] Web UI reflects the current jam mode and power level in real time.  
+   - [ ] Serial CLI commands produce the same output as the original Cypher Pulse.  
+   - [ ] No memory leaks after 24 hours of continuous operation.  
+3. **Regulatory compliance statement** – Include a prominent disclaimer that the device is for **authorized research only** and must be used in a shielded chamber or anechoic enclosure.
+
+---
+
+## 4. Technical Report on Jamming Mechanics
+
+### 4.1 How the Cypher Pulse Jammer Works
+
+The core jamming algorithm is implemented in `toggleJammingMode()` (lines 939‑958 of `cypher‑pulse.ino`):
+
+```cpp
+if (jammingmode == 0) {
+    jammingmode = 1;
+    receivingmode = 0;
+    randomSeed(analogRead(0));
+    for (i = 0; i < 60; i++) {
+        ccsendingbuffer[i] = (byte)random(255);
+    };
+    CC1.SendData(ccsendingbuffer, 60);
+    CC2.SendData(ccsendingbuffer, 60);
+}
+```
+
+Once activated, the `loop()` continuously re‑sends the same random buffer (or generates a new one) as long as `jammingmode == 1`. The transmission is **synchronous** – `SendData()` blocks until the packet is fully clocked out over SPI and the CC1101’s FIFO is empty.
+
+### 4.2 Spectral Characteristics
+
+- **Modulation**: ASK/OOK produces a sin(x)/x spectrum with nulls at multiples of the symbol rate (9.6 kHz).  
+- **Deviation**: The configured 47.6 kHz deviation is irrelevant for OOK, but the CC1101’s internal shaping filters still limit the rise/fall times, reducing harmonic content.  
+- **Occupied bandwidth**: Approximately **2× symbol rate + frequency deviation** ≈ 20 kHz for narrowband OOK, but the actual measured bandwidth is closer to 800 kHz due to the sharp transitions of random data.
+
+### 4.3 Timing Analysis
+
+In **SPECIAL** mode, the main project replicates Cypher Pulse’s timing:
+
+```cpp
+if ((uint32_t)(millis() - lastMs) < 10u) return;
+esp_fill_random(pkt, 60);
+(void)radio1.transmit(pkt, 60);
+```
+
+Thus each radio transmits a 60‑byte packet every **10 ms**, resulting in a **6 kBaud** effective data rate (60 bytes × 8 bits / 0.01 s = 48 kbps). This periodic burst pattern can be more effective against certain types of rolling‑code systems than continuous noise.
+
+### 4.4 Advantages & Limitations
+
+**Advantages**  
+- Simple to implement and debug.  
+- Random payloads avoid unintended correlation with legitimate signals.  
+- Dual‑radio operation doubles the jamming coverage.
+
+**Limitations**  
+- Blocking `SendData()` prevents other tasks (UI updates, network serving) during transmission.  
+- Fixed packet size and delay may not be optimal for all target systems.  
+- No adaptability to changing RF environments (e.g., automatic frequency hopping).
+
+---
+
+## 5. Step‑by‑Step Integration Roadmap
+
+### Week 1 – Preparation
+- **Day 1‑2**: Complete the parameter mapping table (Phase 1).  
+- **Day 3‑4**: Set up SDR test bench (RTL‑SDR + GNU Radio) for baseline measurements of the original Cypher Pulse hardware.  
+- **Day 5**: Create a new branch `feature/cypher‑pulse‑integration` in the main project repository.
+
+### Week 2 – Core Implementation
+- **Day 1‑2**: Enhance `SPECIAL` jam mode with configurable packet size, delay, and radio selection.  
+- **Day 3‑4**: Add frequency‑preset quick‑select buttons to the web UI.  
+- **Day 5**: Implement the Cypher‑Pulse‑style OLED sub‑menu (re‑using existing button/encoder drivers).
+
+### Week 3 – Testing & Validation
+- **Day 1‑2**: Run unit tests and fix any regressions.  
+- **Day 3‑4**: Perform hardware‑in‑the‑loop integration tests; capture SPI and GDO0 waveforms.  
+- **Day 5**: Conduct RF spectrum comparisons between the original Cypher Pulse and the enhanced main project (SPECIAL mode).
+
+### Week 4 – Polishing & Documentation
+- **Day 1‑2**: Add error‑handling safeguards (thermal, SPI, heap) and log messages.  
+- **Day 3‑4**: Update the web UI help text and serial CLI documentation.  
+- **Day 5**: Final validation against the pre‑release checklist; merge to `main` branch.
+
+### Ongoing – Maintenance
+- Monitor field reports for any unexpected behavior.  
+- Keep the parameter mapping table up‑to‑date with future library updates.  
+- Consider adding an “adaptive” jam mode that uses RSSI feedback to concentrate energy on the strongest detected signal.
+
+---
+
+## 6. Conclusion
+
+The Cypher Pulse module provides a proven, straightforward jamming technique that can be seamlessly integrated into the more sophisticated dual‑CC1101 lab instrument. By following the structured integration plan outlined above, the combined system will retain the simplicity and effectiveness of the original Cypher Pulse while gaining the robustness, configurability, and extensive telemetry of the main project.
+
+The proposed testing protocols and error‑handling safeguards ensure that the integrated jammer operates reliably under continuous use and meets the stringent requirements of authorized RF research applications.
+
+---
+*Document generated on 2026‑04‑02*  
+*Project directory: `/Users/drjones/Library/Mobile Documents/com~apple~CloudDocs/dev shit life/car fob killer`*

docs/MAINTENANCE.md

@@ -0,0 +1,17 @@
+# Maintenance
+<!-- stewardship-standard: maintenance-v1 -->
+
+## Stewardship Rules
+
+- Keep generated files, build outputs, copied SDKs, and raw firmware binaries out of Git unless they are the source of truth.
+- Keep credentials, tokens, dumps, private messages, session stores, and local machine paths out of commits.
+- Prefer small commits with clear intent and a matching issue or release note.
+- Preserve upstream attribution when code is copied, forked, or adapted.
+
+## Routine Checks
+
+- README still describes what the project does.
+- Setup instructions still work.
+- Security policy is accurate for the current risk level.
+- Changelog records user-visible changes.
+- License status is explicit.

docs/PROJECT_HANDOFF.md

@@ -0,0 +1,14 @@
+# Project Handoff
+<!-- stewardship-standard: project-handoff-v1 -->
+
+## What This Repo Needs From A Maintainer
+
+- A one-paragraph project summary in README.md.
+- Confirmed setup instructions.
+- Confirmed license status.
+- Confirmed provenance for imported code and binaries.
+- A known-good verification command, test, build, flash, or demo path.
+
+## Current Stewardship State
+
+This repo has baseline governance files, wiki pages, issue templates, labels, milestones, and a readiness issue. The next maintainer should replace generic stewardship notes with project-specific facts.

docs/PROVENANCE_CHECKLIST.md

@@ -0,0 +1,12 @@
+# Provenance Checklist
+<!-- stewardship-standard: provenance-checklist-v1 -->
+
+Use this before claiming ownership or publishing artifacts.
+
+- [ ] Identify original upstream source, if any.
+- [ ] Record fork URL, commit, tag, or archive source.
+- [ ] Preserve third-party notices and license files.
+- [ ] Separate local patches from imported code where practical.
+- [ ] Record binary build inputs, toolchain versions, and source commit.
+- [ ] Publish checksums for release assets.
+- [ ] Mark unknown-origin content as blocked until resolved.

docs/RELEASE_PROCESS.md

@@ -0,0 +1,20 @@
+# Release Process
+<!-- stewardship-standard: release-process-v1 -->
+
+## Before Tagging
+
+- Confirm the default branch builds, runs, or flashes as documented.
+- Confirm no secrets, private data, generated dependency trees, or raw binaries are accidentally committed.
+- Confirm license and upstream provenance are documented.
+- Update CHANGELOG.md.
+- Attach binaries only as release assets with SHA256 checksums and source commit references.
+
+## Release Notes
+
+Include:
+
+- Purpose of the release.
+- Commit hash or tag.
+- Build environment.
+- Known limitations.
+- Verification performed.

docs/ROADMAP.md

@@ -0,0 +1,20 @@
+# Roadmap
+<!-- stewardship-standard: roadmap-v1 -->
+
+## Now
+
+- Confirm the project purpose in the README.
+- Confirm build, run, or flash instructions on a clean machine.
+- Classify license status and upstream provenance.
+- Close the stewardship readiness checklist issue.
+
+## Next
+
+- Add project-specific tests or verification steps.
+- Publish the first verified release only after provenance and security review.
+- Replace placeholder wiki notes with project-specific architecture or hardware details.
+
+## Later
+
+- Add examples, screenshots, wiring diagrams, or demo media where useful.
+- Decide whether duplicate or experimental branches should be archived.

docs/SECURITY_REVIEW.md

@@ -0,0 +1,14 @@
+# Security Review
+<!-- stewardship-standard: security-review-v1 -->
+
+## Required Checks
+
+- [ ] No credentials, tokens, cookies, API keys, private keys, or session files.
+- [ ] No private user data, dumps, card data, logs, or captures that should not be stored.
+- [ ] No copied dependency trees where package managers or SDK installers should be used instead.
+- [ ] No unexplained binaries in source history.
+- [ ] Risky behavior is documented and scoped to authorized lab use.
+
+## Release Gate
+
+A release is blocked until the checklist is complete or a maintainer explicitly records why the item does not apply.

include/config.h

@@ -24,69 +24,71 @@
 // Web server
 #define WEB_PORT 80
 
-// Jamming configuration
+// Jamming: max CC1101 TX (+10 dBm). External PA gain added to ERP calculation.
-#define JAMMING_ENABLED true           // Start jamming immediately on boot
+// Jam always starts after boot self-test; use web “Stop Jamming” (or capture REC) to pause for RX/capture.
-// CC1101 only accepts 8 discrete power levels (index 0-7):
+#define DEFAULT_AUTO_START_JAM true
-// { -30, -20, -15, -10, 0, 5, 7, 10 } dBm
+#define JAM_EXT_PA_GAIN_DB    30       // Gain of external RF amplifier (e.g. 30 dB / 1 Watt)
+// CC1101 only accepts 8 discrete power levels (index 0-7); jam path always uses max (10 dBm).
 #define JAM_POWER_LEVELS      8
-#define DEFAULT_JAM_POWER_IDX 7        // index into power table (7 = 10 dBm, max)
+#define DEFAULT_JAM_POWER_IDX 7        // 10 dBm — full device output (see TI SWRS061 PATABLE / output power)
-// External amplifier gain in dB (used only for display — does not affect CC1101 output)
-#define DEFAULT_AMP_GAIN_DB   20
 
-// Modulation parameters for jamming
+// Modulation parameters for jamming (LFSR drives GDO0 in direct async TX)
-// Deviation 380 kHz = CC1101 hardware maximum.
+#define JAM_BITRATE_KBPS 250.0f        // baseband / channel filter context for RadioLib begin()
-// Carson's rule BW ≈ 2*(380 + 125) ≈ 1010 kHz of noise per hop.
+#define JAM_FREQ_DEV_KHZ 380.0f        // default passed to begin(); per-radio deviation applied after init
-// With ~1 MHz per hop we get solid overlap between steps and leave no gaps.
+#define JAM_RX_BW_KHZ    812.0f        // wide RX BW for begin()
-#define JAM_BITRATE_KBPS 250.0f        // 250 kbps → 125 kHz baseband, maximises noise energy
+// GDO0 toggle rate during jam.
-#define JAM_FREQ_DEV_KHZ 380.0f        // CC1101 max deviation → ~1 MHz noise per hop (was 120)
+// 100 kHz (10 µs period) gives plenty of LFSR noise (AM sidebands at ±100, ±300, ±500 kHz)
-#define JAM_RX_BW_KHZ    812.0f        // Maximum RX BW
+// and leaves enough CPU time for the Arduino interrupt dispatcher to avoid WDT boot-loops.
+#define JAM_LFSR_KEY_HZ    100000
 
-// Frequency sweep — full coverage of all known car-key-fob sub-GHz bands
+// Fixed dual-carrier jamming: each radio holds one frequency at full TX power (TI CC1101 freq + deviation).
-//
+// Many NA ~315 MHz RKE remotes are ASK/OOK (see TI CC1101 datasheet MDMCFG2.MOD_FORMAT). Jam path uses OOK on
-// Radio 1 (CC1101 #1) — 300–320 MHz  [CC1101 Band 1: 300–348 MHz]
+// R1 so LFSR on GDO0 keys the PA (broad AM sidebands). Set JAM_R1_USE_OOK 0 for 2-FSK only at JAM_DEV_KHZ_R1_WIDE.
-//   Honda/Acura (US): 303.825 MHz
+// Fobs may sit on 314.8–315.2 MHz — measure with an SDR and retune JAM_LOCK_FREQ_1_MHZ if needed.
-//   Chamberlain/LiftMaster: 310.0 MHz
+#define JAM_LOCK_FREQ_1_MHZ    315.0f
-//   Toyota/Lexus/Scion: 314.98 MHz
+#define JAM_LOCK_FREQ_2_MHZ    433.92f
-//   Ford/GM/Chrysler/Dodge/Jeep: 315.0 MHz
+#define JAM_DEV_KHZ_R2_WIDE    380.0f
-//   Linear Delta-3 / LiftMaster: 318.0 MHz
+#define JAM_DEV_KHZ_R1_NARROW  25.0f   // probe / RadioLib begin() only
-//
+#define JAM_DEV_KHZ_R1_WIDE    380.0f  // max CC1101 2-FSK deviation on R1 when OOK fails or JAM_R1_USE_OOK=0
-//   With 1 MHz/hop: 25 steps × 0.83 MHz spacing → solid overlap, 75ms full cycle at 3ms dwell
+#define JAM_R1_USE_OOK         1       // 1 = R1 jam ASK/OOK (typical NA); 0 = wide 2-FSK on R1
-#define SWEEP_1_CENTER_MHZ  310.0f
-#define SWEEP_1_SPAN_MHZ    20.0f      // 300–320 MHz
-#define SWEEP_1_STEPS       25         // 0.83 MHz/step, well within 1 MHz hop bandwidth
 
-// Radio 2 (CC1101 #2) — 390–436 MHz  [CC1101 Band 2: 387–464 MHz]
+// Precision jam: narrow 2-FSK on both + slower LFSR (energy in a smaller RF slice).
-//   Chamberlain/LiftMaster: 390.0 MHz
+#define JAM_PRECISION_DEV_R1_KHZ  28.0f
-//   Holtek-based remotes: 418.0 MHz
+#define JAM_PRECISION_DEV_R2_KHZ  55.0f
-//   Somfy RTS / SMC 5326: 433.42 MHz
+#define JAM_PRECISION_LFSR_HZ       40000
-//   Global standard (BMW/VW/Audi/Mercedes/Hyundai/Kia…): 433.92 MHz
-//   Nero Radio / some Asian fobs: 434.42 MHz
-//
-//   With 1 MHz/hop: 60 steps × 0.77 MHz spacing → no gaps, 180ms full cycle at 3ms dwell
-#define SWEEP_2_CENTER_MHZ  413.0f
-#define SWEEP_2_SPAN_MHZ    46.0f      // 390–436 MHz
-#define SWEEP_2_STEPS       60         // increased from 47 for guaranteed overlap
 
-// Dwell per hop — 3ms balances CC1101 lock time vs cycle speed
+// Pulse jam: slow square wave (spoofs preamble AGC)
-// Full cycle: R1 = 75ms, R2 = 180ms → any target frequency is jammed at least every 180ms
+#define JAM_PULSE_HZ           2000
-// Car fob TX window is typically 200–500ms so every transmission gets hit
+
-#define SWEEP_DWELL_MS      3
+// Flood jam: packet-mode random payloads (mcore1976-style bursty TX); deviation for symbol spread.
+// 61 bytes max: CC1101 64-byte FIFO minus 1 length byte (variable-length mode) minus 2 bytes margin.
+// 64 caused TXFIFO_UNDERFLOW — RadioLib writes MIN(len, FIFO_SIZE-1)=63 bytes but CC1101 expects 64.
+#define JAM_FLOOD_PKT_BYTES    61
+#define JAM_FLOOD_DEV_R1_KHZ   140.0f
+#define JAM_FLOOD_DEV_R2_KHZ   200.0f
+
+// Special jam: 60-byte random payloads with 10ms delay (cypher-pulse exact clone).
+
+// SmartRF-style dump: config space only (TI SWRS061); PATABLE/ strobes not included.
+#define CC1101_CFG_REG_LAST    0x2E
 
 // 0.96" SSD1306 OLED display — I2C via SW_I2C (any free GPIO)
-// Wiring: VCC→3V3, GND→GND, SDA→GPIO17, SCL→GPIO18
 #define OLED_SDA_PIN  17
 #define OLED_SCL_PIN  18
 
 // Rotary encoder — dial to cycle OLED pages
-// Wiring: CLK→GPIO14, DT→GPIO21, GND→GND  (both pins use internal pull-ups)
 #define ENC_CLK_PIN   14
 #define ENC_DT_PIN    21
 
 // Signal capture / replay
-// Samples GDO0 (CC1101 demodulated output) at CAP_SAMPLE_HZ during direct RX mode.
+#define CAP_SAMPLE_HZ    100000
-// Bit-packed into a static buffer. Replay drives GDO0 in direct TX mode at same rate.
+#define CAP_DURATION_S   4
-#define CAP_SAMPLE_HZ    100000                         // 100 kHz sample clock
+#define CAP_BUF_BYTES    ((CAP_SAMPLE_HZ * CAP_DURATION_S) / 8 + 8)
-#define CAP_DURATION_S   4                              // max capture window (seconds)
+#define CAP_HISTORY_MAX  8
-#define CAP_BUF_BYTES    ((CAP_SAMPLE_HZ * CAP_DURATION_S) / 8 + 8)  // ~50 KB
+
+// ESP-NOW mesh
+#define ESPNOW_BEACON_MS     750
+#define ESPNOW_PEER_STALE_MS 12000
+#define ESPNOW_MAX_PEERS     8
 
 #endif

platformio.ini

@@ -27,3 +27,5 @@ board_build.extra_flags =
   -DBOARD_HAS_PSRAM
 
 monitor_speed = 115200
+; Avoid macOS picking Bluetooth “serial” instead of the ESP32 USB-UART
+upload_port = /dev/cu.usbserial-A5069RR4