← Back to Home

🔧 Development Guide - VR Simulator

Complete reference for developers contributing to the project.

Full Project Structure

esp32_VR_sim/
├── src/
│   ├── main.c                 # Application entry point
│   ├── vr_signal.c/h          # Waveform generation (DMA setup)
│   ├── freq_detector.c/h      # GPIO4 frequency measurement
│   ├── can_reader.c/h         # CAN interface (disabled)
│   └── CMakeLists.txt
├── platformio.ini             # Build configuration
├── plot_vr_signals.py         # Waveform visualization
├── docs/                       # This documentation
└── README.md                  # User-facing overview
        

C Firmware Architecture

Waveform Generation (vr_signal.c)

The core signal generator uses DMA for zero-CPU-overhead streaming:

• DMA Pipeline: Cyclic descriptor chain (4 descriptors × 512 bytes)
• Sample Rate: 48 kHz via APLL (Audio PLL)
• Resolution: 8-bit DAC output (0-255 codes)
• Pattern: Subaru 36-2-2-2 (36 teeth with 6 missing)

Frequency Detection (freq_detector.c)

Measures GPIO4 PWM input to extract RPM:

• Edge Counter: Rising edge detection every 100ms
• Smoothing: Exponential filter (8:1 ratio)
• Mapping: RPM = (frequency_Hz / 50.0) × 1500.0

Task Structure

FreqDetectorTask (100ms intervals)
├── Count rising edges on GPIO4
├── Calculate frequency
└── Trigger waveform regeneration if needed

FreqPrintTask (1 second intervals)
├── Print current frequency and RPM
└── Log any RPM changes

WaveformReaderTask (on-demand)
├── Read new frequency from detector
├── Generate new waveform table
└── Update DMA descriptors
        

Python GUI Architecture

The desktop controller (rpm_controller_gui.py) uses:

• Tkinter: GUI framework
• PySerial: Serial communication
• Threading Model: Main thread handles UI, background thread reads serial

Configuration Parameters

Located in src/vr_signal.c, VR signal characteristics:

cfg->rpm               = 3000.0f;        // Default operating point
cfg->tooth_spacing_deg = 10.0f;         // Degrees between teeth
cfg->compression_depth = 0.10f;         // Compression effect amplitude
cfg->compression_order = 2.0f;          // Harmonic order
cfg->peak_volts        = 1.0f;          // Signal peak voltage
cfg->vref              = 3.3f;          // DAC reference (3.3V)
cfg->sample_rate_hz    = 48000;         // DMA sample rate
        

Build Instructions (Detailed)

With PlatformIO CLI

# Install dependencies
pio pkg install

# Build for ESP32
pio run -e esp32

# Upload to connected board
pio run -e esp32 -t upload

# Monitor serial output
pio device monitor --baud 115200
        

With VSCode + PlatformIO

Open the workspace and use the PlatformIO sidebar buttons for Build, Upload, and Monitor.

Release Process (Step-by-Step)

1. Ensure all commits are on main branch
2. Run full build: pio run
3. Extract binaries to docs/ folder
4. Update docs/index.html with new version
5. Update docs/manifest.json with release info
6. Test web flasher in browser
7. Create Git tag: git tag -a v1.2.0 -m "Release 1.2.0"
8. Push to GitHub: git push origin v1.2.0
9. Create GitHub Release with binaries attached

Git Workflow & Best Practices

Branch Strategy

• main: Stable releases only (tagged)
• feature/*: Feature development branches
• bugfix/*: Bug fixes
• docs/*: Documentation updates

Commit Guidelines

Good: "Add CAN frequency sync from 0x280"
Bad: "fixed stuff"

Good: "Fix edge case in compression modulation (closes #42)"
Bad: "fix"
        

Web Flasher Updates

After each release, the web flasher must be updated:

1. Run: pio run
2. Copy binaries to docs/:
   • firmware_v1_2_0.bin → .pio/build/esp32/firmware.bin
   • bootloader.bin → .pio/build/esp32/bootloader.bin
   • partitions.bin → .pio/build/esp32/partitions.bin
3. Update docs/index.html version number
4. Test: Open docs/index.html in Chrome and test flash

Performance Characteristics

• CPU Load: <1% (DMA handles all signal generation)
• Memory: ~8-10 KB waveform buffer + 2 KB overhead
• Latency: <100ms for RPM updates
• Accuracy: ±2% frequency (GPIO edge measurement limited)
• Power: ~150mA typical operation