🚀 Quick Start
- Connect to Timer: Click "Connect" button and select "G4 Race Timer" from the Bluetooth device list
- Setup Event: Enter event name, date, location, and track distance in Event Setup tab
- Register Cars: Add cars in Car Registration tab (Middle School or High School division)
- Run Time Trials: Assign cars to lanes and run qualifying races in Time Trials tab
- Generate Bracket: Create single or double elimination bracket in Brackets tab
- Run Tournament: Race through the bracket matches until a champion is crowned!
📋 Event Setup
Purpose: Configure basic event information and save/load events.
- Event Details: Name, date, location, and track distance (feet + inches)
- Save Event Details: Saves current event to browser storage and archives it for later
- Load Previous Event: Quick access to your last 20 saved events
- Export Event to File: Download complete event as .json file for backup or sharing
- Import Event from File: Load a previously exported .json event file
🏎️ Car Registration
Purpose: Register all cars participating in the event.
- Two Divisions: Middle School (MS) and High School (HS) - tracked separately
- Car Number: Unique identifier for each car (e.g., 42, 007, etc.)
- Driver Name: Name of the person racing the car
- DQ Checkbox: Mark a car as disqualified (removes from brackets/leaderboards)
- Edit/Delete: Modify car details or remove cars entirely
⏱️ Time Trials
Purpose: Run qualifying races to determine bracket seeding.
- Lane Assignment: Select which cars race in Lane 1 and Lane 2
- BLE Warning: Yellow warning shows if timer is not connected via Bluetooth
- Race Results: Automatically appear when timer sends BLE notification
- Accept/Re-run: Accept the result or run the race again
- Best Time Tracking: System automatically keeps the fastest time for each car
- Results Table: Click column headers to sort by finish time or reaction time
💡 Tip: Run multiple time trials for each car to get their best qualifying time!
🏆 Brackets
Purpose: Generate and run tournament brackets.
Bracket Configuration
- Bracket Size: 4, 8, or 16 cars
- Bracket Type:
- Single Elimination: Lose once, you're out. Simple and fast.
- Double Elimination: Lose twice to be eliminated. Winners bracket, losers bracket, and grand finals.
- Seeding: Automatic based on time trial results (fastest = #1 seed)
Visual Bracket Tree
- Columns: Each round shown as a vertical column (scroll horizontally for large brackets)
- Current Match: Glows orange - this is the race you should run next
- Winner: Green background with bold border
- Loser: Grayed out with strikethrough
- TBD: Participants not yet determined (muted, italic)
Running Bracket Races
- Click the "🏁 Race" button on the current (glowing) match
- Confirm you want to start the race
- Run the race on your physical timer
- Results automatically appear in a popup modal
- Click "✓ Accept & Advance" to advance the winner
- Or click "🔄 Re-run" to race again
- Or click "✏️ Manual Override" to manually select the winner
Double Elimination Details
- Winners Bracket: Green border - undefeated racers
- Losers Bracket: Yellow border - racers who lost once, fighting for second chance
- Grand Finals: Blue border - Winners bracket champion vs Losers bracket champion
- Advancement: Win in winners bracket → advance. Lose → drop to losers bracket
- Elimination: Lose in losers bracket → eliminated from tournament
📊 Leaderboards & Export
Purpose: View top performers and export data.
- Fastest Finish Times: Top 10 racers by finish time (per division) with 🥇🥈🥉 medals
- Fastest Reaction Times: Top 10 racers by reaction time (per division)
- Export Time Trials CSV: Download all time trial results as spreadsheet
- Export Brackets CSV: Download all bracket race results as spreadsheet
🔧 Troubleshooting
BLE Connection Issues
- Can't find G4 Race Timer: Make sure ESP32 is powered on and BLE is enabled
- Connection drops: Move computer/tablet closer to timer, avoid obstacles
- No race results: Check that BLE is connected (green dot) before clicking Race button
- Browser compatibility: Use Chrome, Edge, or Opera (Safari doesn't support Web Bluetooth)
Data Issues
- Lost event data: Use "Load Previous Event" to access last 20 events from browser storage
- Backing up events: Use "Export Event to File" to save .json backup files
- Moving to another computer: Export event, transfer .json file, then import on new device
- Browser cleared: If browser cache is cleared, localStorage data is lost. Always export important events!
Bracket Issues
- Not enough qualifiers: Run more time trials until you have enough cars for your bracket size
- Wrong winner advanced: No undo - use "Manual Override" carefully or re-generate bracket
- DQ'd car still showing: Check the DQ checkbox in Car Registration tab
💡 Tips & Best Practices
- Save early, save often: Click "Save Event Details" after major milestones
- Export before important events: Create a .json backup before championships/finals
- Test BLE first: Run a practice race to verify timer connection before the real event
- Multiple time trials: Let racers run 2-3 time trials to get their best qualifying time
- Use tablets: App works great on iPads/tablets for track-side use
- Keep browser open: Closing the browser tab during an event is safe, data persists in localStorage
💻 System Requirements
- Browser: Chrome, Edge, or Opera (Web Bluetooth support required)
- Hardware: G4 Race Timer with ESP32-S3 BLE Server
- Connection: Bluetooth Low Energy (BLE) capability on your device
- Storage: Browser localStorage enabled (for event saving)