a44462e905
Bug 1 — FLOOD mode TXFIFO_UNDERFLOW (config.h): JAM_FLOOD_PKT_BYTES was 64. RadioLib variable-length mode writes one length byte to the FIFO first (dataSent=1), then MIN(len, FIFO_SIZE-1)=63 data bytes. CC1101 was told to send 64 bytes but only 63 were in the FIFO, causing TXFIFO_UNDERFLOW every packet. Changed to 61 bytes (safe margin). Bug 2 — STATUS register read protocol (main.cpp): cc1101ReadRegister sent 0x80|addr for all addresses. Per SWRS061 §10.2, for addresses 0x30-0x3D burst-bit=0 selects a command strobe, NOT a register read. VERSION register (0x31) was actually triggering an SIDLE strobe and returning the status byte. Fixed: use 0xC0|addr (read+burst) for addr >= 0x30 to correctly access status registers. Made-with: Cursor
264 lines
16 KiB
Markdown
264 lines
16 KiB
Markdown
# 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`* |