← Back to Home

📚 Documentation Hub

Complete documentation for the ESP32 VR (Variable Reluctance) Crank Sensor Signal Simulator project.

📖 Documentation Files

⚡ Quick Start

Start here if you're new to the project.

5-minute project overview
Architecture diagram
How-to for building and running
Common tasks
Troubleshooting quick reference

Best for: Getting up and running quickly, understanding the big picture

🔧 Development Guide

Complete reference for developers.

Full project structure explanation
C firmware architecture (tasks, modules, ISR patterns)
Python GUI architecture and threading model
Detailed build instructions
Complete release process (step-by-step)
Git workflow and best practices
Web flasher updates

Best for: Deep understanding, contributing code, releasing new versions

✅ Release Checklist

Step-by-step checklist for every release.

Pre-release validation
Binary extraction
Git tagging
GitHub Release creation
Web flasher updates
Final verification
Sign-off template

Best for: Publishing releases, ensuring nothing is forgotten

🔍 How to Use This Documentation

I want to...

...get the project running right now
→ Read Quick Start (5 minutes)
...understand how everything works
→ Read Development Guide (30 minutes)
...modify the C code
→ See "C Firmware Architecture" in Development Guide
...modify the Python GUI
→ See "Python GUI Overview" in Development Guide
...publish a new release
→ Follow Release Checklist step-by-step
...update the web flasher
→ See "Documentation Index Updates" in Development Guide
...troubleshoot a problem
→ Check "Troubleshooting" sections in Quick Start and Development Guide

🚀 Quick Links

Building

pio run                    # Build
pio run -t upload         # Build and upload
pio device monitor        # Serial monitor

Releasing

Follow Release Checklist
Build: pio run
Extract binaries to docs/
Update index.html and manifest.json
Create GitHub Release with binaries

GUI

python rpm_controller_gui.py

📋 Version History

1.2.0 (2026-07-02) - Multi-pattern support, real-time RPM feedback
1.1.0 (2026-06-15) - Improved frequency detection
1.0.0 (2026-05-20) - Initial release

🔐 Key Safety Rules

C Code

⚠️ No printf() in ISRs! - Interrupt handlers must be non-blocking
⚠️ No build clean without reason - Takes time to rebuild
⚠️ Always test on real hardware - Not just simulation

Git

⚠️ Never force push to main - Use pull requests
⚠️ Always create release tags - Format: vX.Y.Z
⚠️ Keep build artifacts out of repo - Use .gitignore

Releases

⚠️ Update web flasher after release - Users need to see new version
⚠️ Attach all binaries - Bootloader, partitions, firmware
⚠️ Test on real hardware - Before marking as "Latest"

📞 Getting Help

Build issues: Check Quick Start troubleshooting
Design questions: Read Development Guide
Release procedures: Follow Release Checklist
Code understanding: See source code comments in src/
GitHub Issues: Check project issues for known problems

📝 Project Overview

ESP32 VR Simulator - An embedded firmware project that simulates automotive variable reluctance (VR) crank sensor signals.

Main Components

Embedded C - Firmware for ESP32 (ESP-IDF, FreeRTOS, DMA)
Python GUI - Desktop controller (Tkinter, pyserial, Pillow)
Web Flasher - Browser-based flashing interface

Supported Patterns

Subaru 36-2-2-2 (primary)
60-2 (alternative)
Custom patterns (via waveform tables)

Key Features

Real-time RPM adjustment (200-10000 RPM)
Differential VR signals (GPIO25/26)
Dynamic frequency control (GPIO4 input)
Serial communication (UART0)
Desktop GUI with rotary knob
Web flasher for easy firmware updates

🎯 Next Steps

First Time Here?

Read this file (you are here)
Open Quick Start (5-10 minutes)
Build the project: pio run
Run the GUI: python rpm_controller_gui.py

Want to Contribute?

Read Development Guide (architecture)
Check Release Checklist (release process)
Follow Git workflow (feature branches, pull requests)

Need to Release?

Ensure all changes are committed and tested
Follow Release Checklist step-by-step
Update index.html and manifest.json
Test web flasher in browser

Documentation Updated: 2026-07-02
Project Version: 1.2.0
Last Build: 2026-07-02