"Respect the Laws of Physics."

The M.A.S.S. Trap is a forensic-grade physics laboratory disguised as a Hot Wheels track speedometer. It utilizes commercial LiDAR and enterprise IoT hardware to enforce the laws of Mass, Momentum, and Kinetic Energy on 1:64 scale traffic.

This project was engineered by a former Police Detective and Digital Forensics Instructor to bridge the gap between law enforcement precision and childhood wonder.

• The Name: A nod to the creator's past life enforcing speed limits -- and his family name, Massfeller. It is a literal "Speed Trap" for Hot Wheels.
• The Legacy: Inspired by a grandfather who raced Formula Vee in the 70s/80s. In Formula Vee, raw horsepower didn't win races; efficiency and momentum conservation did.
• The Mission: To teach the next generation that Science is Cool, Math is Power, and while you can't break the laws of physics... you can certainly measure them.

Try the Interactive Demo → — No hardware needed. All 5 themes. Simulated races.

Already have an ESP32-S3 N16R8 and an IR break-beam sensor? You're 5 minutes from your first race.

# 1. Clone & flash
git clone https://github.com/Ryan4n6/MASS-Trap.git && cd MASS-Trap
pio run -t upload                    # Flash firmware via USB
pio run -t uploadfs                  # Upload web UI + audio files

# 2. Configure
# Connect to WiFi: "MASSTrap-Setup-XXXX" → browser opens automatically
# Pick role (finish/start/speedtrap), enter your WiFi creds, save

# 3. Race
# Open http://masstrap.local on any device → ARM → release car → data appears

That's it. One ESP32 as a finish gate gives you timing, speed, momentum, kinetic energy, a leaderboard, 5 themes, and a full physics dashboard served from the chip itself. Add a second ESP32 as a start gate for precision split timing. Add a third as a speed trap for mid-track velocity profiling. All auto-discover each other via ESP-NOW.

No internet required. No app to install. No account to create. Just physics.

→ Need the full parts list? Parts Store — 3 budget tiers from $25 to $120. → Building with your kid? Parent's Wiring Guide — Ages 8+ with parent supervision. → Science fair? Parent & Teacher Guide — Variables, hypothesis, and rubric mapping done for you.

Unlike civilian-grade Arduino projects, The M.A.S.S. Trap runs on the Interceptor Spec -- a modified, high-performance stack designed for real-time telemetry, heavy data logging, and audio synthesis.

The system hosts its own web app (no internet required), turning any phone, tablet, or laptop into the M.A.S.S. Trap Command Center.

• 5 Selectable Themes: Interceptor (navy+gold default), Classic (Hot Wheels orange), Daytona (NASCAR racing), Case File (police detective), Cyber (terminal green).
• Real-Time Telemetry: Instant display of Scale MPH, Actual MPH, Finish Time (ms), Momentum, KE, G-Force.
• Suspect Tracking:
  • "Staged": LiDAR confirms vehicle presence at the start gate.
  • "Clocked": Speed trap sensors capture mid-track velocity.
  • "Booked": Finish gate logs the final time and physics data.
• The "Lead Sled" Leaderboard: Tracks new records with an animated podium ceremony.
• Mechanic's Log: A digital notebook to correlate car modifications (graphite, weight) with performance gains.
• Chart.js Visualization: Speed vs Run and KE vs Weight scatter plots, auto-updating after each race.
• Ghost Car Comparison: Personal best delta display with new record/slower indicators.
• Physics Explainer: Live formula cards showing actual race values.
• Speed Profile: Start/mid/finish velocity comparison when speed trap data is available.
• Kiosk Mode: ?kiosk URL parameter or Ctrl+K hides controls for science fair display — judges see data only.
• Dual-Layout Navigation: Desktop manila folder tabs + mobile bottom thumb bar. Consistent across all pages.

• Microsecond-precision timing via hardware interrupts on IR break-beam sensors
• Thread-safe ISR timing -- spinlock-protected 64-bit timestamps prevent torn reads on dual-core ESP32-S3
• ESP-NOW peer-to-peer communication between gates (sub-millisecond latency)
• Clock synchronization between devices with drift-filtered logging
• Automatic race detection -- arm the system, release the car, results appear instantly
• Real-time physics calculations: elapsed time, speed (mph/km/h), scale speed, momentum (kg*m/s), kinetic energy (Joules), G-force
• Mid-track velocity profiling via optional speed trap node (demonstrates acceleration/deceleration)
• Imperial/Metric units -- configurable display units with WebSocket broadcast

• Automatic car staging -- solid-state LiDAR detects car at start gate
• Auto-arm -- car present > 1 second triggers automatic system arming
• Dashboard indicator -- live "LIDAR TARGET ACQUIRED" status on Command Center
• Configurable threshold -- adjustable detection distance via web UI
• UART interface -- 115200 baud, 9-byte frames with checksum validation
• Signal strength filtering -- rejects low-confidence readings
• Fully optional -- disabled by default, zero overhead when off

• Non-blocking WAV playback via ESP32 I2S DMA ring buffer
• Race event sounds -- arm chime, countdown, go tone, finish fanfare, new record alert
• Web-based upload -- drag-and-drop WAV files to device via config page
• Volume control -- adjustable 0-21 levels via web UI
• Fully optional -- disabled by default, zero overhead when off

• Mid-track velocity measurement -- dual IR sensors ~10cm apart
• Microsecond ISR timing -- hardware interrupt on both sensors
• ESP-NOW integration -- sends velocity data to finish gate automatically
• Dedicated status page -- shows last speed, peer status, sensor config

• Web-based setup -- captive portal on first boot, no code editing required
• WiFi or Standalone mode -- connect to your router, or create its own network
• Pin configuration -- all GPIO assignments configurable via web UI
• Peer discovery -- automatically find other M.A.S.S. Trap devices on the network
• WLED integration -- LED strip effects for race states (idle, armed, racing, finished)
• OTA updates -- flash new firmware over WiFi, no USB cable needed
• Full system snapshot -- one-click backup/restore of config + garage + history
• Clone mode -- restore snapshot to a new device (strips network identity)
• 5 visual themes -- switch look-and-feel from Interceptor to Hot Wheels Classic, Daytona, Case File, or Cyber
• Kiosk mode -- presentation mode for science fairs hides controls, shows data only
• Imperial/Metric units -- configurable display units (mph or km/h) with timezone selection

• Case numbers — Sequential MASS26-XXXX format with chain of custody tracking
• QR-coded evidence tags — Printable labels with case number, car info, and scannable QR code
• NFC auto-identification — NTAG213 stickers on cars auto-select vehicle and arm track when scanned
• Photo documentation — Upload evidence photos linked to case numbers via cloud hosting
• Forensic-grade logging — Every data point traceable back to exact car, weight, condition, and trial

• Guided testing workflow — Experiment Setup → Vehicle Intake → Evidence Prep → Pre-Flight → Data Collection → Results
• Test matrix generation — Locard's Exchange Principle ordering prevents systematic bias
• Auto-advance — System prompts operator through each run with audio cues
• Sanity checks — Alerts on suspicious times (too fast, too slow, identical runs) with KEEP/RETRY options
• CSV export — Raw data and summary tables formatted for science fair rubric requirements
• Auto-generated lab report — Complete science fair report with hypothesis, variables, data tables, analysis, conclusion
• Persistence — State saved to localStorage + ESP32 at every transition; full recovery on disconnect

• GitHub-direct OTA — Download and flash firmware updates directly from GitHub releases
• MD5 verification — Integrity check before flashing, dual OTA partition safety net
• TLS secured — Embedded root CAs for secure HTTPS downloads
• Update detection — Dashboard shows breathing red badge when new firmware is available
• Manual upload fallback — Drag-and-drop .bin upload with progress bar

• Web-based serial monitor -- view device logs over WiFi at /console
• NTP-stamped log lines -- [HH:MM:SS.mmm] wall-clock timestamps (uptime fallback before NTP sync)
• Ring buffer capture -- 8KB of recent serial output, auto-refreshing
• WiFi diagnostics -- /api/wifi-status with RSSI, connection state, and failure reasons
• File browser -- inspect, edit, and manage files on the device filesystem
• Device info -- IP, uptime, free memory, peer status at a glance

• Unified firmware -- single codebase runs as start gate, finish gate, or speed trap
• Role-appropriate UI -- finish gate serves full dashboard; start gate and speed trap serve lightweight status pages
• LittleFS-first web serving -- pages served from filesystem with PROGMEM fallback (no upload needed, but LittleFS files take priority when present)
• Custom 16MB partition -- 3MB app (with OTA) + ~9.9MB LittleFS for data/audio + 64KB coredump
• Graceful degradation -- audio, LiDAR, and speed trap are optional; existing gates work without them
• Reliable captive portal -- OS-specific handlers for iOS, Android, and Windows CNA detection

• Target Board: ESP32-S3 Dev Module (Enable USB CDC On Boot)
• Flash Size: Select 16MB (128Mb)
• PSRAM: Select OPI PSRAM

The "Interceptor" requires a custom memory map to fit the audio assets and logs.

The partitions.csv in the project root defines: 3MB app (with OTA) + ~9.9MB LittleFS + 64KB coredump.

• PlatformIO: Handled automatically via platformio.ini
• Arduino IDE: Place partitions.csv in the sketch folder; select Flash Size 16MB (128Mb)

PlatformIO (Recommended)

1. Install PlatformIO Core (Python 3.10+)
2. Clone this repo and run pio run — all dependencies install automatically

Arduino IDE

1. Arduino IDE 2.x
2. ESP32 Board Package — Add https://espressif.github.io/arduino-esp32/package_esp32_index.json to Board Manager URLs
3. Required Libraries (install via Library Manager):
   • WebSockets by Markus Sattler
   • ArduinoJson by Benoit Blanchon

No external library needed for the TF-Luna LiDAR — it uses the built-in HardwareSerial UART driver.

IR Sensor (Start / Finish Gate)

IR Sensor Signal  ->  GPIO 4 (default, configurable)
IR Sensor VCC     ->  5V / 3.3V (check your sensor)
IR Sensor GND     ->  GND
Status LED        ->  GPIO 48 (NeoPixel on ESP32-S3 DevKit)

Benewake TF-Luna LiDAR (optional)

VCC  ->  5V
GND  ->  GND
TX   ->  ESP32 GPIO 39 (RX) (default, configurable)
RX   ->  ESP32 GPIO 38 (TX) (default, configurable)

Note: The TF-Luna runs in UART mode at 115200 baud.

MAX98357A I2S Amplifier (optional)

BCLK  ->  GPIO 15 (default, configurable)
LRC   ->  GPIO 16 (default, configurable)
DIN   ->  GPIO 17 (default, configurable)
VIN   ->  5V
GND   ->  GND

Speed Trap Node (dual IR sensors)

Sensor 1 Signal  ->  GPIO 4 (default, configurable)
Sensor 2 Signal  ->  GPIO 5 (default, configurable)
Sensor spacing: ~10cm apart on track

1. Clone this repository:

   git clone https://github.com/Ryan4n6/MASS-Trap.git
   cd MASS-Trap

2. PlatformIO (Recommended):

   pio run -t upload          # Build + flash via USB
   pio run -t uploadfs        # Upload LittleFS data files (audio, etc.)
   pio run -t monitor         # Serial monitor

   Arduino IDE: Open MASS_Trap.ino, set board to ESP32S3 Dev Module, Flash Size 16MB, PSRAM OPI, then Upload.

3. After flashing, connect to WiFi SSID: MASSTrap-Setup-XXXX

4. Configure role, WiFi, pins via the captive portal at http://192.168.4.1

5. Access the Command Center at http://masstrap.local

6. Respect the laws of physics.

Once configured, you never need a USB cable again:

PlatformIO:

pio run -e ota -t upload     # Flash over WiFi

Arduino IDE: Go to Tools → Port, select the network port (masstrap.local), and click Upload.

Web pages update automatically — they're embedded in the firmware.

The OTA password defaults to admin — change it in the config page for security.

MASS-Trap/
├── platformio.ini             # PlatformIO build configuration (recommended)
├── partitions.csv             # Custom 16MB partition table (3MB OTA + 9.9MB LittleFS + 64KB coredump)
├── MASS_Trap.ino              # Main entry point: WiFi, NTP, OTA, boot logic
├── config.h / .cpp            # Configuration struct, named constants, JSON persistence
├── web_server.h / .cpp        # HTTP routes, WebSocket, API handlers, SerialTee ring buffer
├── espnow_comm.h / .cpp       # ESP-NOW protocol: 14 message types, discovery, clock sync
├── finish_gate.h / .cpp       # Finish gate: spinlock-protected timing, race results, physics
├── start_gate.h / .cpp        # Start gate: IR trigger, LiDAR auto-arm
├── speed_trap.h / .cpp        # Speed trap: dual ISR velocity measurement, ESP-NOW send
├── lidar_sensor.h / .cpp      # TF-Luna UART: frame parsing, presence state machine
├── audio_manager.h / .cpp     # MAX98357A I2S: WAV loading, non-blocking DMA playback
├── wled_integration.h / .cpp  # WLED HTTP API: effect control, auto-sleep
├── html_*.h                   # PROGMEM fallback pages (index, config, console, start, speedtrap, chartjs)
├── push_ui.sh                 # Convert data/*.html to PROGMEM html_*.h headers
├── generate_stats.sh          # Auto-regenerate docs/stats.json from live git data
├── kristina.sh                # Generate The Special K Report (terminal, JSON, HTML modes)
│
├── data/                      # LittleFS files (uploaded via pio run -t uploadfs)
│   ├── dashboard.html         # Command Center — 6-phase lab manager, evidence, all features (~185KB)
│   ├── history.html           # Evidence Log — race history with full physics data
│   ├── system.html            # System Config — WiFi, pins, peers, track, audio, LiDAR, WLED
│   ├── about.html             # The Special K Report™ — project stats, builders, live API status
│   ├── science_fair_report.html  # Auto-generated forensic lab report from experiment data
│   ├── main.js                # Shared JavaScript utilities
│   ├── style.css              # Shared stylesheet (5 themes, dual-layout nav)
│   ├── console.html           # Debug console with NTP-timestamped serial log
│   ├── css.html               # CSS component reference map (all themes, live preview)
│   ├── start_status.html      # Start gate lightweight status page
│   ├── speedtrap_status.html  # Speed trap lightweight status page
│   └── *.wav                  # Audio effect files (8-bit, 16kHz mono)
│
├── docs/                      # GitHub Pages site (https://ryan4n6.github.io/MASS-Trap/)
│   ├── index.html             # Landing page with live interactive dashboard demo
│   ├── wizard.html            # Build Wizard — interactive wiring guide, 3-tier telemetry
│   ├── parents.html           # Parent & Teacher Guide — science fair helper
│   ├── parents-guide.html     # Parent's Wiring Guide — terminal block migration
│   ├── judges.html            # Judge Showcase — science fair project page
│   ├── store.html             # Curated parts store by budget tier
│   ├── stats.js               # Shared auto-populator (data-stat attributes from stats.json)
│   └── stats.json             # Centralized project metrics (auto-generated)
│
├── BACKLOG_PLANS.md           # 14 backlog items with full implementation designs
├── MESH_AUTONOMY_DESIGN.md    # "10-Code" distributed ESP-NOW protocol upgrade design
├── DAYTONA_THEME_BRIEF.md     # Daytona NASCAR theme design specification
├── DAYTONA_NARRATIVE.md       # Personal essay on the Daytona heritage
├── HARDWARE_CATALOG.md        # Hardware inventory reference
├── CHANGELOG.md               # Detailed release notes (Keep a Changelog format)
├── README.md
└── .gitignore

• Hub Scoreboard Device -- Waveshare ESP32 display as the central data authority with SD card storage
• Multi-Lane Support -- Multiple finish sensors for parallel lane timing
• Tournament Bracket Mode -- Head-to-head elimination bracket with automatic advancement

• NFC Car Tagging -- NTAG213 stickers auto-select car and arm track on scan
• 6-Phase Science Fair Lab Manager -- Guided forensic testing workflow with test matrix generation, auto-advance, and sanity checks
• Browser Firmware Update -- GitHub release detection, MD5-verified OTA, breathing badge notification
• Evidence System — Case numbers, QR tags, photo documentation, chain of custody
• Science Fair Report Generator — Auto-generated forensic lab report from experiment data
• GitHub Pages Site — Interactive demo, parent guide, judge showcase, parts store, build wizard
• Community Feedback (Giscus) — GitHub Discussions-powered comments and reactions on all pages
• Google Analytics — GA4 tracking across all GitHub Pages
• XSS Hardening & CSP — Quote-aware escHtml(), Content-Security-Policy meta tags on all pages, API key hygiene

• Theme Engine -- 5 selectable themes (Interceptor, Classic, Daytona, Case File, Cyber) with localStorage persistence
• Dual-Layout Navigation -- Desktop manila folder tabs + mobile bottom thumb bar across all pages
• Kiosk Mode -- Science fair presentation mode via ?kiosk or Ctrl+K (hides controls, shows data only)
• Modular Web UI -- LittleFS-first serving with PROGMEM fallback; new dashboard, history, and system pages
• Thread-Safe Timing -- Spinlock protection for all 64-bit ISR timing variables across dual-core ESP32-S3
• NTP Timestamps -- Wall-clock time in serial log ring buffer with timezone support
• Captive Portal Fix -- OS-specific handlers for iOS/Android/Windows CNA detection
• Regional Settings -- Imperial/metric units and configurable timezone
• WiFi Diagnostics -- /api/wifi-status endpoint, RSSI logging, human-readable failure reasons
• Peer Hotlinks -- Clickable hostname.local links for peer devices in all status pages
• Named Constants -- 20+ magic numbers extracted to #define constants
• Dead Code Cleanup -- Removed unused functions from lidar, WLED, and ESP-NOW modules

• M.A.S.S. Trap Rebrand -- Full project rebrand with police shield/badge themed Command Center
• Custom 16MB Partition Table -- 3MB app (with OTA) + 10MB LittleFS for audio and data
• Full System Snapshot -- One-click backup/restore of config + garage + history with clone mode
• TF-Luna LiDAR -- UART solid-state LiDAR for car staging detection and auto-arm
• Audio System -- MAX98357A I2S amplifier with non-blocking WAV playback via DMA
• Speed Trap Node -- 3rd ESP32 role with dual IR sensors for mid-track velocity measurement
• Leaderboard Podium Overlay -- Animated ranking display after each race
• Mechanic's Log -- Per-car notes with timestamps for tracking modifications
• Speed Profile -- Start/mid/finish velocity comparison when speed trap data available

• Chart.js Data Visualization, Ghost Car Comparison, Physics Explainer Panel
• LED Visualizer Bar, API Authentication, WLED Auto-Sleep, XSS Protection

• Unified firmware, Captive portal config, ESP-NOW, Embedded web UI
• WLED integration, Google Sheets, OTA, Backup/restore, Web console

MIT License -- use it, modify it, teach with it.

Built for my sons. May you always find the thrill in the data.

In memory of Richard Massfeller — General Contractor, Formula Vee racer, and the original builder. He built a 7ft pencil for a science fair. We built this.

In memory of Sam Troia and Stephen "Beaver" Massfeller — the uncles who shaped who we are.

🏠 Project Site · 📦 GitHub · 📥 Releases · 🛒 Parts Store

Firmware assistance by Claude (Anthropic).