Documentation

Mini 4WD Timer and Race System is a complete race timing solution for Tamiya Mini 4WD. It pairs with an RGB Timer sensor device over Bluetooth, manages your racers and race-day rosters, times 3-lane heats with millisecond precision, and can broadcast the live timer screen to viewers anywhere in the world.

System Components

Requirements

1. Browser: Google Chrome or Microsoft Edge (desktop or Android). Bluetooth is only available in these browsers, and only when the page is served over HTTPS.
2. Timer device: a compatible RGB Timer device.
3. Account: accounts are created by an administrator — see User Management. If you don't have one yet, ask your race organizer.
4. Internet connection: required for signing in and for viewer synchronization. The Bluetooth link itself works over the local connection.

First Sign-In

1. Click the Login button (top-right) and enter the username and password your administrator gave you, or sign in with Google.
2. On your very first sign-in you'll be asked to set a password — choose one you'll remember, it replaces the temporary one.
3. After signing in, complete the race setup: create a Race, add Racers, and build your Roster.

The User Menu

Click the User button (top-right) to open the user menu. It gives quick access to, in order: Change Password, API Keys (manage your REST API keys), OTA WiFi (the timer's firmware-update WiFi credentials), User Management (admins only), Settings, Documentation (this manual and the API reference), and About (version and device info).

1. Power on the timer device and wait a few seconds for it to initialize.
2. Click the Connect button (top-left) on the timer screen.
3. In the browser's pairing dialog, select your RGB Timer device. Devices are identified by name and serial number.
4. The button turns red and shows Disconnect once connected. The timer screen un-blurs and shows the live state.

What Happens on Connect

1. The web app requests the timer's configuration: serial number, firmware version, lane names, and OTA WiFi settings.
2. A live session is created so viewers and other screens (e.g. a second laptop at the finish line) can follow the race in real time.
3. The timer and the web screen synchronize: names you type on the web are sent to the device, and race states detected by the device are reflected on screen.

Connection States

Race Lifecycle

Every heat moves through a fixed sequence of states, shown as a colored badge above the main timer:

Step by Step

1. Select a roster row on the Round page to send its three racers to lanes A, B, and C. Racer names appear instantly on the timer screen.
2. Use the Clock button to run a countdown start (default 3-2-1-Go), or start directly from the timer device.
3. The main timer runs until all lanes finish. The LAST LAP state is triggered automatically by the timer's route sensors — no manual step needed.
4. As each car finishes, its lane shows the exact time and a large 1st / 2nd / 3rd position badge.
5. Lanes that don't finish are marked with the DNF label (default COURSED-OUT) once the maximum finish time is reached, and the timer pauses automatically.
6. Press RESET to advance the reset cycle: FINISHED → SUMMARY → READY. Press it once to review the summary, once more to clear for the next heat.

Broadcast the live timer screen over the internet so friends, family, or a venue projector can follow the race from any browser — no login needed on their side.

1. Click the Monitor button to start sharing the timer screen.
2. A live broadcast session starts. The top navigation bar is excluded from the capture — viewers only see the timer itself.
3. Share the generated link (or scan the QR code) with viewers. They'll see the live timer in their browser within a few seconds.
4. The broadcast continues until you press the Monitor button again to stop sharing.

A Race holds all the event details — who organized it, where it happens, and when. Everything else (racers, roster, timer sessions) belongs to a race.

Creating a Race

1. Open Race → Races and click New Race (or edit the active one).
2. Fill in the details: title, organizer, venue name and address, country, postal code, start/end dates and times.
3. Optionally upload a race logo and an organizer logo (shown on the flyer and header), a track layout picture, and link a race regulation document.
4. Set Number of winners to control how many positions advance to the next round (default 3: 1st, 2nd, and 3rd).
5. Save the race, then make it Active — the active race is used by the Roster, Racers, Flyer, and timer pages.

Managing Races

1. Only one race can be Active at a time — activating another race automatically deactivates the previous one.
2. Use Duplicate to copy a race's details for a new event — perfect for recurring weekly meetups.
3. Open the Flyer to view and share a printable event page with the venue, dates, logos, and track layout. The regulation link is hidden automatically if none is set.
4. Add the race to your personal calendar from the Calendar page — it generates a calendar entry with the event details.
5. Use the Delete action to remove a race. Deleting a race does not delete its racers — clean those up on the Racers page if needed.

The Racers page is your central list of everyone who competes. Each racer has a name and an optional team name.

1. Open Race → Racers and click Add Racer. Enter the racer name and, optionally, the team name.
2. Names can be edited inline at any time — click a name, change it, and press Enter. Changes flow to the roster suggestions automatically.
3. Use the search box to find racers quickly when the list grows large.
4. Delete a racer with the delete action on their row when they no longer compete.

The Round page is your race-day heat sheet. Each round contains rows; each row is one heat with three lanes (A, B, C).

Building the Roster

1. Open Race → Round and navigate to the round you want (use the round selector to move between rounds).
2. Click a lane cell and pick a racer from the suggestions (they come from your Racers list).
3. Press Enter to move to the next cell. At the last cell of a row, Enter creates a fresh row underneath.
4. Use the row actions to delete a row or swap two rows when the running order changes.
5. On mobile, each row shows a number badge (its running order); on desktop the whole grid is visible at once.

Recording Results

1. Click the ○ badge on a cell to mark 1st (gold) or 2nd (silver) place. Click again to cycle or clear.
2. Winners advance automatically to the next round based on the race's Number of winners setting.
3. Lock a round to freeze it once results are confirmed — no accidental edits afterwards.

Final Round

1. Set which round is the Final Round on the race (Race → Races → edit race).
2. Toggle Final Round on the deciding round: it is auto-populated from the previous round — 1st-place finishers compete for positions 1-3, 2nd-place for 4-6, 3rd-place for 7-9, and so on.
3. No progression happens after the final round — record the finishing order to crown your champions.

Sending a Heat to the Timer

1. Click any row to send its three racers to the timer lanes A, B, and C.
2. The selected row is highlighted and syncs live to every open screen — the timer screen, viewer screens, and any other connected laptop all switch to the same heat.

Open User → Settings to configure the system. Settings are saved per user and applied to every screen you're signed into.

API keys let external apps — race management software, a second dashboard, or your own scripts — update your roster and control the timer screen securely.

1. Open User → API Keys in the User menu and click Generate.
2. Copy the key immediately — it is shown only once. Only a short prefix is stored afterwards so you can recognize it in the list.
3. Use the key with the REST API to update your roster, set the racer names on the live timer screen, and trigger timer commands from external apps.
4. Delete a key to revoke access immediately for anything using it. Generate a new key if an old one may have leaked.

1. Open User → User Management to create accounts for other race officials. Only admins see this menu.
2. Create a user with a username and temporary password (or let them sign in with Google). The new user sets their own password at first sign-in.
3. Assign the admin role to users who should manage accounts; regular users run races. Admins can change anyone's password and role.
4. Each user manages their own races, racers, and API keys. The creation date of each account is shown in the list.
5. Use Change Password in the User menu to update your own password at any time.

The timer won't connect

1. Make sure you're using Chrome or Edge on desktop or Android, and that the address starts with https://.
2. Check that the timer device is powered on — its display should be lit.
3. Close other tabs or apps that may already be connected to the device — a BLE device accepts only one connection.
4. Move the timer and the computer closer together; BLE range is a few meters.
5. If it still fails, toggle the device off and on, then click Connect again.

Viewer can't see the broadcast

1. Make sure the broadcast is still running (the Monitor button is active) and the viewer uses the current link — starting a new broadcast invalidates old links.
2. Ask the viewer to reload the page. If it stays on "Connecting", their network may block WebRTC — a stricter firewall (hotel, office, mobile data) is the usual cause; try another network.

Race state seems stuck

1. Press RESET — it walks the cycle FINISHED → SUMMARY → READY. Press twice if needed to get back to a clean READY state.
2. If the timer screen is blurred, the device disconnected — reconnect and reset again.

API returns 401 Unauthorized

1. Check that the key was copied completely — it must start with the m4wd_ prefix.
2. Verify the key still exists in User → API Keys; deleted keys stop working immediately.
3. Confirm you're sending it as the x-api-key header, api_key query parameter, or api_key body field.

Lane times look wrong

1. Clean the track sensors — dust and direct sunlight are the most common causes of missed or phantom laps.
2. Make sure cars are placed behind the start sensor before starting, and that only one car is in each lane.
3. If a lane shows a time but no position badge, the car may have jumped lanes — the route validation ignores such anomalies; re-run the heat if needed.