476 lines
40 KiB
Markdown
476 lines
40 KiB
Markdown
# RC RaceCore
|
||
|
||
RC timing and race control for clubs: live timing from AMB/MyLaps decoders through AMMC, race day control with EFRA/IFMAR-style start procedures, qualifying and finals, series and cups, practice statistics with mobile driver profiles, announcements with an offline voice, and overlays for screens and OBS. Everything runs locally on one computer (Windows or Linux) with a SQLite database - no cloud service and no internet needed at the track.
|
||
|
||
Swedish version: [README.sv.md](README.sv.md) · Changes: [CHANGELOG.md](CHANGELOG.md) · Plans: [ROADMAP.md](ROADMAP.md) · The running version is shown at the bottom of the menu.
|
||
|
||
## Contents
|
||
|
||
- [Highlights](#highlights)
|
||
- [Screenshots](#screenshots)
|
||
- [Quick start](#quick-start)
|
||
- [Using RaceCore](#using-racecore)
|
||
- [Race day](#race-day)
|
||
- [Creating races](#creating-races)
|
||
- [Series / cup](#series--cup)
|
||
- [Practice and training statistics](#practice-and-training-statistics)
|
||
- [Audio and announcements](#audio-and-announcements)
|
||
- [Overlays and OBS](#overlays-and-obs)
|
||
- [Sponsor events with shared cars](#sponsor-events-with-shared-cars)
|
||
- [Data, backups and import/export](#data-backups-and-importexport)
|
||
- [Security](#security)
|
||
- [Video guides](#video-guides)
|
||
- [Installation](#installation)
|
||
- [Decoders and AMMC](#decoders-and-ammc)
|
||
- [Development and tests](#development-and-tests)
|
||
|
||
## Highlights
|
||
|
||
- **Race Day page** with heat queue, preflight checks and one-click start.
|
||
- **Start procedure as in EFRA/IFMAR:** a count-down with announcements (2 min, 1 min, 30 s, 10, 9 … 3), hold for the grid, flying start for qualifying, and grid start for finals: after "3" the announcer says "Starting to the sound of the tone" and the tone follows 1-3 s later. The start and the end of a race are signalled with a tone and a stop signal by default; trumpet, air horn or the classic sounds can be chosen under Settings → Audio.
|
||
- **Transponder check** during the count-down: a green tick for every driver seen, and a wrong transponder fixed in one click.
|
||
- **Qualifying and finals:** generated from the entry list with evenly split heats, A/B/C finals, bump-ups, points tables, tie-breaks and a drag-and-drop grid.
|
||
- **Series / cup:** a points table, best N or drop X, a club-members-only option, standings per class, and each round run from the series page.
|
||
- **Judging:** penalties and lap changes, all logged and undoable.
|
||
- **Practice statistics** per driver, class and track layout: stints, consistency, achievements, goals, and a personal mobile profile with a QR code.
|
||
- **Clean statistics:** suspiciously short practice laps (shortcuts) are flagged automatically and removed in one click.
|
||
- **Announcements** in Swedish or English with a local neural voice (Piper, offline). Races play the passing tone only, as timing systems do.
|
||
- **Overlays** for screens and OBS, with places gained/lost since the start.
|
||
- **Safe data:** SQLite, an automatic backup before every start, full export/import, and an optional admin PIN.
|
||
|
||
## Screenshots
|
||
|
||
Click an image to open the full-resolution version.
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/overview-active-session.jpg"><img src="docs/screenshots/overview-active-session.jpg" alt="Dashboard with active session" /></a><br><strong>Dashboard with active session</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/race-setup-wizard.jpg"><img src="docs/screenshots/race-setup-wizard.jpg" alt="Race Setup wizard" /></a><br><strong>Race Setup wizard</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/overlay.jpg"><img src="docs/screenshots/overlay.jpg" alt="Full live overlay" /></a><br><strong>Full live overlay</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/leaderboard-overlay.jpg"><img src="docs/screenshots/leaderboard-overlay.jpg" alt="Leaderboard overlay" /></a><br><strong>Leaderboard overlay</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/training-overview.jpg"><img src="docs/screenshots/training-overview.jpg" alt="Practice statistics overview" /></a><br><strong>Practice statistics overview</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/training-extra-stats.jpg"><img src="docs/screenshots/training-extra-stats.jpg" alt="Detailed practice statistics with pace heatmap and stint analysis" /></a><br><strong>Detailed practice statistics</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/series.jpg"><img src="docs/screenshots/series.jpg" alt="Series / cup with numbered steps" /></a><br><strong>Series / cup</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/judging-current.jpg"><img src="docs/screenshots/judging-current.jpg" alt="Judging and race corrections" /></a><br><strong>Judging and race corrections</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/race-audio-settings.jpg"><img src="docs/screenshots/race-audio-settings.jpg" alt="Race sounds and announcements" /></a><br><strong>Race sounds and announcements</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/race-manage-tabs.jpg"><img src="docs/screenshots/race-manage-tabs.jpg" alt="Event Manager's Live & results tab" /></a><br><strong>Event Manager's Live & results tab</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/decoder-settings.jpg"><img src="docs/screenshots/decoder-settings.jpg" alt="Decoder configuration" /></a><br><strong>Decoder configuration</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/managed-ammc.jpg"><img src="docs/screenshots/managed-ammc.jpg" alt="Managed AMMC configuration" /></a><br><strong>Managed AMMC configuration</strong></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="docs/screenshots/guide.jpg"><img src="docs/screenshots/guide.jpg" alt="In-app setup guide" /></a><br><strong>In-app setup guide</strong></td>
|
||
<td width="50%"><a href="docs/screenshots/race-day.jpg"><img src="docs/screenshots/race-day.jpg" alt="Race Day with quick actions during a running practice" /></a><br><strong>Race Day</strong></td>
|
||
</tr>
|
||
</table>
|
||
|
||
## Quick start
|
||
|
||
**Windows 11** (PowerShell):
|
||
|
||
```powershell
|
||
winget install --id Git.Git --exact --source winget # only if "git --version" fails
|
||
Set-Location $HOME
|
||
git clone https://git.dio.nu/Public/Live_RC.git Live_RC
|
||
Set-Location .\Live_RC
|
||
.\windows\install.bat
|
||
```
|
||
|
||
**Linux (Ubuntu/Debian)** with Node.js 22 or 24:
|
||
|
||
```bash
|
||
git clone https://git.dio.nu/Public/Live_RC.git Live_RC
|
||
cd Live_RC
|
||
npm ci && npm run verify
|
||
npm start
|
||
```
|
||
|
||
Then open `http://localhost:8081`, or `http://<server-ip>:8081` from another computer on the race network. The in-app **Guide** (menu) and the [video guides](#video-guides) walk through the first decoder connection, drivers and the first race. Full steps: [Installation](#installation).
|
||
|
||
## Using RaceCore
|
||
|
||
The menu follows how a race day works: **Start** (Dashboard, Race Day), **Create** (Race Setup, Sponsor events, Series / cup), **Run and follow** (Timing, Judging, Overlay, Training stats, Results archive), **Directory** (Classes, Drivers, Cars) and **System and help** (Settings, Guide). The interface is in Swedish or English.
|
||
|
||
### Race day
|
||
|
||
**Race Day** is the operator's page; everything that *runs* a session happens here, while Timing is for *following*:
|
||
- **Quick actions** at the top: **Start practice** (continue or start an Open Practice), **New track layout** (during practice) and **Create race**. The Dashboard has the same three common tasks.
|
||
- **A session picker** and the buttons that apply right now: Start, Pause, Resume, Finish, **↻ Run again** for a stopped or finished heat, qualifier or final (laps, results and clock reset), and for practice **Reset – new practice day**. Practice uses plain words and has no start lights. The picker lists today's races grouped per race (plus anything running); older races and other days' rounds are under **Show all sessions**.
|
||
- **Live race** for the race controller, right under the clock while a heat, qualifier or final runs: the running order with laps, last lap, best lap, gap to the car ahead and to the leader, and the estimated finish (laps and time when the time is up). The heat's fastest lap is purple, a personal best on the last lap green, and a bar shows how far into the lap each car is (red = late). After the heat it shows the result.
|
||
- The **heat queue** shows the current, next and after-next heat in running order: practice, qualifying round by round (Q1 H1, Q1 H2, Q2 H1 …), then finals from the lowest (C, B, A). When a heat is done, **▶ Next** selects the next one in one click. The session lists in Race Setup and on Race Day follow the same order, so a heat deleted and made again lands in its right place; **▲▼** on a session in Race Setup moves it earlier or later.
|
||
- **Today's schedule** (at the bottom) puts every class raced that day in one running order with times: practice, then each qualifying round with the classes taking turns, then the finals. Set the first start and the break between heats; **▲▼** change the order. A heat that starts late, runs long or is paused moves the rest of the day. Heats already run fold into one line (✓ 6 heats run – show), and the next heat is marked.
|
||
- **🖨 Print running order** gives times, classes, heats and drivers for the board in the pits.
|
||
- **📺 Drivers' board** (`/public-overlay/schedule`, also under Overlay) shows what is on track, the next three heats with their drivers, then the rest of the day. A heat that has been called is highlighted "Called – get ready". It works on a phone or a TV in the pits.
|
||
- **Calling a heat:** when a heat is 10 minutes away (set under **Call**), Race Day asks the race controller: **📢 Call now** reads the heat and its drivers over the speakers and highlights it on the drivers' board; **Later** asks again in 2 minutes. With the autopilot on, heats are called on their own.
|
||
- **▶ Run the day automatically** starts each heat's count-down on its own when the schedule says so, and waits (saying why) while a heat runs, the decoder is offline or a heat is not ready. It runs only in the browser where it was turned on. **■ Stop autopilot** to run heats by hand; turning it on again carries on with the next heat not yet run. **⏸ Pause the day** pauses the heat on track (or holds the count-down) and the autopilot until **Resume the day**.
|
||
- **Race overview** (under the heat queue): the whole race of the current event in one place - the podium from the A final, then practice, qualifying and finals that open and close, each with the standings and every heat's result (laps, result, best lap, and the car in sponsor heats). **Print**, **PDF** and **CSV** export the whole race with every heat.
|
||
- **Speaker panel** (under the start buttons): track call, track clear, red flag, pause, resume, false start and marshal warning. Under **Sound and calls** are quick switches that save at once: mute all, lap time calls, race leader calls, practice hype and the speaker cues.
|
||
- **Preflight** checks the decoder, participants, transponders (missing or duplicated), the lap window, the grid and audio. Blockers come first, each with a shortcut to the right setting. The min/max lap time can be edited right there.
|
||
- **An automatic SQLite backup** is taken before every start.
|
||
|
||
**Start procedure (EFRA/IFMAR):** Start runs a count-down first. Choose Go, 30 s, 1, 1:30, 2, 3 or 5 min; the default is set per event for qualifying and finals.
|
||
- **During the count-down:**
|
||
- The track is open.
|
||
- The announcer calls "Heat 3 starts in 2 minutes", then every minute, 30 s and 10 s.
|
||
- For a grid start it also calls "cars to the grid" at 30 s and counts "10, 9 … 3" second by second.
|
||
- **Buttons:**
|
||
- **Hold** (while cars are put on the grid) and **Resume**.
|
||
- **+1 min**.
|
||
- **To 30 s** (grid restart).
|
||
- **To 10 s**.
|
||
- **Go now**, which warns about drivers not seen.
|
||
- **Cancel**.
|
||
- **When the count-down runs out the heat starts by itself.**
|
||
- **Grid start** (mass/position): after "3" it is quiet; the start lights come on and the horn sounds 1-3 s later (IFMAR 4.2.6).
|
||
- **Flying start** (default for qualifying): the signal and "Clock is running". Each car's clock starts at its own first crossing, and a late car's clock starts at the latest 150 % of a lap (EFRA 9.3).
|
||
- **Staggered start:** cars are called out one by one.
|
||
- **Transponder check:** every driver in the heat gets a green tick when their transponder crosses during the count-down. A missing driver's transponder can be changed in the panel, or linked to an unknown transponder that just crossed.
|
||
- **Pause, resume and finish** work during the heat. Follow-up time lets the last lap finish after the clock.
|
||
|
||
**Timing** shows the live leaderboard (laps, gap to leader and ahead, own delta, best and last lap), recent passings with invalid short laps marked, the grid for position starts, and a session replay (1-10x).
|
||
|
||
**Judging** has the speaker panel on top and is where race corrections are made - also after a heat, qualifier or final is finished (a protest, a car found illegal): pick the heat under **Heat to judge**. Penalties take a **reason** that is logged; there is an own time (e.g. +10 s), **DSQ** (classified last; in qualifying last-place points, as in EFRA) and **DNF**. While the heat runs, **Calls to the driver** - Attention (blue flag), Official warning, Stop & go, Drive through - are called out by the speaker and logged; two official warnings offer a DSQ (EFRA). Results, standings, the race overview and the archive update at once; if the finals were already made from qualifying, Judging warns. Also: ±laps, ±seconds and reset, plus removing or restoring any lap. Everything is logged with time and can be undone; the log exports as JSON. In qualifying, heats and finals this is the only place for penalties; Timing shows the corrections and has an **Open in Judging** button. Practice has no penalties, but laps can be cleaned up right on Timing (see [practice](#practice-and-training-statistics)).
|
||
|
||
Lap validation:
|
||
- **Min lap time** rejects shortcuts and false hits.
|
||
- **Max lap time** starts a new statistics stint after a break; the long lap still counts in the race.
|
||
|
||
### Creating races
|
||
|
||
**Race Setup** has two ways in:
|
||
- **Quick Open Practice:** just a name. It creates an untimed all-transponder session and goes straight to Timing; no class, drivers or format are needed.
|
||
- **Create Race Wizard:** Basics → Participants → Session plan → Confirm. Choose a class and a preset, pick the drivers, and the practice/qualifying (or team race) sessions are created.
|
||
|
||
The **race list** is grouped so it stays short: **Today** (and anything running), **Upcoming**, and **Done** folded away (races whose heats are all run or whose date has passed). Races on the same date are listed together, each with how far it has come (● running heat, *Next: Q2 H1*, *3/9 run* or ✓ Done). A search box finds older races.
|
||
|
||
In **Manage** the easy setup comes first (the race steps and tabs, or the sponsor setup), then the list of heats; **Add a heat by hand (advanced)** and the branding are folded away. The sessions are grouped per step: practice / seeding, each qualifying round, finals. A step whose heats are all run is folded to one line (✓ Qualifying round 1 · 3/3 run) and opens with a click. Each session shows ▲▼, Edit and Set active; printing, export, the grid and delete are under **⋯**.
|
||
|
||
After creation the race is managed in four tabs (Race Setup → Manage):
|
||
- **Participants & teams:** tick who races. For endurance the **Team race** panel (shown as soon as the Endurance format is picked):
|
||
- **Split the drivers** over N teams in one click, add a team, rename it in its card, add a driver from a list that says which team they move from, remove with ×;
|
||
- a **car per team** (the drivers share its transponder) or the drivers' own transponders;
|
||
- the **length** with quick picks 30 min to 24 h, and **Create team race**;
|
||
- **checks before the start:** fewer than two teams, a team without drivers or transponder, a transponder on two teams, drivers on no team.
|
||
- Run it on Race Day. Drivers change when the pack is flat - no driver-change rules. Teams, cars and the length can be changed while it runs (a broken car, a wrong transponder): the laps stay with the team. **Overlay → Team** shows the top 3 with the active driver and the team standings.
|
||
- **Format:**
|
||
- qualifying rounds, cars per heat, duration and start mode (mass, position, staggered, flying);
|
||
- seeding (best N laps total, average, or consecutive);
|
||
- qualifying points table (placement, by field size, 10-9-8...) and tie-break;
|
||
- finals: legs, counted legs, bump-ups and reserved bump slots;
|
||
- count-down length, follow-up time and the min/max lap time;
|
||
- presets: short technical track, club race, IFMAR style, endurance, or your own saved club presets;
|
||
- **Race actions** at the bottom of the tab:
|
||
- create qualifying from practice (or the entry list); heats are split as evenly as possible, e.g. 9 drivers with max 8 per heat gives 5 + 4;
|
||
- reseed upcoming heats; locked manual grids are respected;
|
||
- create A/B/C finals and apply bump-ups;
|
||
- export the race as a package.
|
||
- **Live & results:**
|
||
- grid editor (drag and drop) and lock;
|
||
- practice, qualifying and final standings, and a finals matrix;
|
||
- print and branded PDF exports;
|
||
- split and pit summaries.
|
||
- **Schedule & print:** the day's running order with planned times, and heat sheets.
|
||
|
||
The **Dashboard** shows schedule drift (planned vs actual). The **Results archive** lists one row per race; pick one to see its race overview, its heats and the exports (print, PDF, CSV, race package), and open a heat for its laps and penalties.
|
||
|
||
### Series / cup
|
||
|
||
Menu **Series / cup** runs a championship over any number of rounds, with freely chosen classes. Each class gets its own standings.
|
||
|
||
1. **Name and classes.**
|
||
2. **Points:**
|
||
- **Who scores:** every driver (open series), or club members only. With members only, drivers from other clubs race and appear in the day result but get no series points, and members are re-ranked without them.
|
||
- **Points table:** the ÖRC table (100, 90, 82, 75, 69 … then −4 per place, min 10), 100-80-70, F1, or your own list.
|
||
- **Counted results:** best N (e.g. 9 of 12), or all run rounds except the X worst. A cancelled round then lowers the count automatically.
|
||
3. **Rounds:** paste the dates, and one race per date and class is created. The button says how many races were made.
|
||
- **Format:** e.g. **ÖRC Winter** (3 × 5 min qualifying with a staggered start where most laps in the time wins, the best 2 rounds compared, max 6 per heat and final, 3 finals of which 2 count). It fills in the number of qualifying rounds, finals and max cars per heat, which can be changed.
|
||
- **Seeding practice before qualifying** (default: on, 5 min, best 3 laps): every race starts with a practice, and the qualifying heats are split on it so drivers of equal pace run together. **Max drivers per seeding group** (default 6, the Max drivers/seed group column per round, 0 = all together) splits the practice into even groups on the series standings when you press ▶ Seeding practice, e.g. 10 drivers with max 5 → 2 groups of 5.
|
||
- **Heat order:** fastest heat last (default) or first. Also set per race in Race Setup.
|
||
|
||
Each round is then run from its row:
|
||
- pick drivers, **Copy from previous** round, or **New driver** for a late entry;
|
||
- change the format for that round (it can differ between rounds and classes);
|
||
- **one button for the next step:** ▶ Seeding practice → Create qualifying → ▶ Run Q1 H1, Q1 H2 … → Create finals → ▶ Run C Final 1, B Final 1, A Final 1 …. A ▶ button selects the session and opens Race Day, where only Start is left;
|
||
- **Status** and **Open**.
|
||
|
||
Deleting a series asks whether its races should be removed from Race Setup too, or kept.
|
||
4. **Standings:**
|
||
- The day placing comes from the final standings (A before B), then qualifying order.
|
||
- No registered lap gives 0. Absence counts as 0 and can be dropped.
|
||
- **✎ Result** on a round sets the day's order by hand (▲▼, add, remove), e.g. when the qualifying went wrong. It replaces the calculated result in the standings, and the round is marked Corrected result. Use the calculated result goes back.
|
||
- Ties go to most wins, then 2nd places, then the latest common round.
|
||
- Print, or export as PDF (wide tables switch to landscape).
|
||
|
||
#### Rookie class (2WD/4WD drivers in their own race)
|
||
|
||
Rookies are not registered again: they race with the driver and transponder they already have in 2WD or 4WD, and 2WD and 4WD can be mixed.
|
||
|
||
1. **Classes:** create a class called Rookie, with no drivers of its own.
|
||
2. **Single race:** in Race Setup, create the race with class Rookie and tick the rookies under Participants → **Drivers from other classes**.
|
||
3. **Series:** tick Rookie under the series' classes. For a series already running, paste the same dates again and press Create rounds: only the missing Rookie rounds are made.
|
||
4. **Each round:** open the driver list on the Rookie row, then tick the rookies under **Drivers from other classes**. Copy from previous takes the same rookies next time.
|
||
|
||
Rookie gets its own standings with the series' points table, count rule and club rule; points never mix with the driver's 2WD/4WD standings. Race format, open practice and lap time limits are not affected.
|
||
|
||
### Practice and training statistics
|
||
|
||
**Practice sessions:**
|
||
- Open Practice can run all season; Free Practice is a rolling best-lap session.
|
||
- **Settings** on the Open Practice row in Race Setup: the shortest and longest lap and the **ranking** - best lap (default), **best N laps in a row** (e.g. 3) or **best X minutes** (most laps inside X minutes, then the shorter time, e.g. 5). Timing, the overlay, Race Day and the results show e.g. "3 laps 52.341" or "17 laps / 5:00.3"; the best lap keeps its own column. A stop in the pits breaks "in a row".
|
||
- **Start practice** on the Dashboard or Race Day continues the running Open Practice, or creates and starts one. **Reset – new practice day** on Race Day clears the day's laps for a new evening; every lap stays in the training statistics.
|
||
|
||
**Track layouts:**
|
||
- Press **New layout** (on Training stats, Race Day or the Dashboard) when the track is rebuilt. A running practice moves onto the new layout, and best laps start over.
|
||
- Each layout can have its own **min/max lap time** for practice. Races always use the event's values.
|
||
- Statistics are per layout, with an "all layouts" overview.
|
||
|
||
**Suspiciously short laps** (practice only):
|
||
- A lap far quicker than the driver's own pace (under 85 % of their median, after 5 laps) is flagged ⚠ - typically a shortcut by a new driver or a child.
|
||
- It counts as a lap but not as a best lap, record or statistic until someone **Approves** it.
|
||
- **Remove** is one click, in the panel on Timing and Race Day, or in the driver's lap list.
|
||
|
||
**Training stats** (menu):
|
||
- The club overview and one page per driver and class show:
|
||
- personal best, averages and consistency;
|
||
- best 3 consecutive laps and the best 5-minute result;
|
||
- stint analysis, 30-minute pace blocks and setup markers with before/after comparison;
|
||
- daily history and achievements;
|
||
- goals with rewards, daily challenges and a shared club goal.
|
||
- **Based on: Practice** (default), **Races** or **All.** Race laps are kept separate and marked 🏁 with race, session and series. Under Races they are listed per race session; a race never forms stints.
|
||
- One person can race several classes. Link the class entries to the same practice profile under Drivers; statistics stay per class.
|
||
|
||
**Mobile profile:**
|
||
- Each driver can get a personal link with a QR code. It shows their own statistics, a practice timer, setup markers and exercises (even laps, step training), and has a choice of practice or race laps.
|
||
- The link uses a random token; no transponders or other drivers are shown.
|
||
- For use over the internet, set the **public address** once for everyone under Settings → System & backup → Public address (domain / DynDNS), e.g. `https://club.dyndns.org:8443`. Left empty, links use the local network address.
|
||
- Proxy only these paths to the internet: `/public-training/*`, `/src/public_training.js` and `/src/public_training.css`. Ready-made Teltonika files are in `scripts/teltonika/`.
|
||
|
||
### Audio and announcements
|
||
|
||
Settings → Audio:
|
||
- **Race sounds:**
|
||
- start lights, random start delay and passing tones (optionally a different tone per driver/car);
|
||
- announcements in Swedish or English for the start, the clock (1 min, 30 s, 10 s), final lap, finish, winner and podium, pit, penalties and race control (track call, red flag, false start, marshal);
|
||
- each event can be switched on or off for effect and voice.
|
||
- **Race control calls** are on the speaker panel on Race Day and Judging, with quick switches for the calls below.
|
||
- **Practice:** a quick lap time call at each passing ("17 six", "18 flat", optionally with the name), pace and hype calls (beat last time, class rank, lap milestones, faster streaks, average down, close to best, duels). Off in qualifying and finals.
|
||
- **Race leader calls:** on a confirmed change of leader and now and then (both, change only, or off).
|
||
- **Calls during a race:** "Passing tone only" (default, like timing systems) or "Speaker" with names, personal bests and new leaders. Practice always gets the full calls.
|
||
- **Local neural voice (Piper):** free and works offline. Install from Settings → Audio → Voice engine, or with `npm run tts:install`.
|
||
- Standard voices: Swedish NST (male) and Lisa (female), English Ryan (male) and Lessac (female).
|
||
- Under **More voices**, one at a time (about 63 MB each): Swedish Alma; British Alan, Northern English, Cori and Alba (Scottish); American Joe, John and Norman.
|
||
- Pre-generate phrases and driver names before race day.
|
||
- If Piper is missing, the browser voice takes over.
|
||
- **Spoken name per driver:** enter a pronunciation or nickname under Drivers and press **🔊 Test pronunciation** to hear it in real announcements.
|
||
|
||
### Overlays and OBS
|
||
|
||
The **Overlay** menu has leaderboard, speaker, results, TV and team modes, plus an OBS mode with layout (leaderboard, TV graphics, grid, lower third), theme (panel, transparent, chroma), rows and columns:
|
||
- Columns: laps, result, best, gap, and **places since the start** (▲/▼ in heats and finals).
|
||
- **TV graphics:** a title plate top left (event and heat) and a timing tower top right with the clock on top and real columns: place / **start position** (e.g. "2 / 3"), driver, laps, time, best and gap, in large bold type with podium colours for the top three. No backdrop of its own, so the camera image shows through. The start position can be turned off and is not shown in practice.
|
||
- **Click a driver** in RaceCore's own overlay to open that driver's training stats (the stand-alone overlay window opens them in a new tab). The public overlay has no such links.
|
||
- **Copy OBS URL** gives a browser-source link; the chosen columns are part of the link.
|
||
- **Overlay windows are read-only:** they do not connect to the decoder and never save, so an overlay on another computer (or in OBS) cannot disturb the race run from Race Day. No admin PIN is needed for that. Run Race Day in one browser at a time.
|
||
- Public overlays live at `/public-overlay/<mode>` and can require a token: set `PUBLIC_OVERLAY_TOKEN` and add `?token=...`. Publish only `/public-overlay/*` through your reverse proxy.
|
||
- Club branding (name, logo, PDF theme) is applied to the sidebar, overlays, mobile profiles and PDFs; branding can also be set per event.
|
||
|
||
### Sponsor events with shared cars
|
||
|
||
**Sponsor events** let guests drive the club's cars, rental-kart style - e.g. 8 drivers on 4 cars. Events → Manage:
|
||
1. **Drivers:** type the names, one per line. They become guests of this event only (never in normal races or practice) and are deleted with it.
|
||
2. **Cars:** tick the cars, or add one with name and transponder.
|
||
3. **Format:** practice per group, qualifying rounds, qualifying start (staggered, flying, mass) and lengths. 8 drivers and 4 cars give 2 groups, 1 practice per group, 2 qualifying rounds and A/B finals. **Create heats**: drivers rotate cars every round.
|
||
4. Run the heats on **Race Day** like a race (▶ Next, Start, Pause, Stop, count-down, start signal and calls). The car's transponder counts for whoever drives it in that heat, and the car is shown next to the driver's name (🚗 Rental 2) on the overlay, the OBS overlay and Race Day's live list.
|
||
5. **Create finals** from qualifying; cars are drawn for the finals. The race overview and the results archive show the car per driver and heat.
|
||
|
||
### Data, backups and import/export
|
||
|
||
- **Storage:**
|
||
- Everything is stored in `data/rc_timing.sqlite`; the browser keeps a local copy and syncs.
|
||
- The menu shows the save status (saved, pending, failed, with **Retry**).
|
||
- Judge corrections are sent straight to the server.
|
||
- **Backups:**
|
||
- automatic before every session start, plus manual ones;
|
||
- the latest 30 are listed under Settings;
|
||
- restore with `npm run backup:restore` (see [Installation](#restore-a-server-backup)).
|
||
- **Export/import** (Settings → Storage):
|
||
- full JSON, or the directory only (classes, drivers, cars);
|
||
- CSV for drivers and cars (Excel/LibreOffice; comma, semicolon or tab). The CSV import merges: it matches on ID, then transponder, then name + class.
|
||
- a single race package from Race Setup;
|
||
- club presets.
|
||
- **Clearing:** drivers, cars, classes, races or training statistics can each be cleared separately, every one with its own confirmation. Export first.
|
||
|
||
Example driver CSV (only `name` is required):
|
||
|
||
```csv
|
||
name;transponder;class;brand;club;country
|
||
Anna Andersson;123456;2WD;;JMK;SE
|
||
Erik Eriksson;654321;4WD;Associated;;
|
||
```
|
||
|
||
### Security
|
||
|
||
RaceCore is meant for a trusted race network:
|
||
- **Admin PIN** (Settings → System & backup, off by default) protects every change through the API. The login lasts 30 days and is throttled against guessing.
|
||
- **Race Controller Master:** one computer at a time runs the race (the decoder, start, pause, resume, stop, false start, resetting a heat and the autopilot, also from the speaker panel). Judging corrections and the other calls work from any computer. The computer running the server (page opened on `localhost`) becomes master on its own and shows a green line "🎙 You are the Race Controller Master" with **Release master**. Phones and other computers follow the race live (updated every second), show "You are following the race …" and become master only when someone presses the button; that computer then remembers the role. They can also prepare drivers and races. Whoever works as race controller presses **Take over as master**, and the previous master lets go of the decoder within seconds. With the admin PIN on, taking over needs a login. Name the computer under Settings → System, e.g. "Speaker booth". Overlays and OBS are always view-only.
|
||
- **House of RC:** under Settings → System → 🏠 House of RC you save the club's API key once (stored on the server only, never shown again) and press **Test connection**. Drivers → **🏠 Fetch from House of RC** fills in names and brands from the transponders (only what you tick), and a known transponder fills in a new driver. With the key of the club running the event, the race wizard's **🏠 Fetch from House of RC** lists the club's events; pick an event and one of its classes, and the name, date, class and entered drivers with their transponders are filled in. Later, Manage → Participants → **🔄 Fetch changes from House of RC** adds late entries and takes out withdrawals. **📤 Send results to House of RC** previews and sends the results to the entries: heats and qualifying during the day, the final placings when the finals are run.
|
||
- **`RC_ADMIN_ALLOWED_CIDRS`** restricts admin changes to certain addresses or networks, e.g. `192.168.1.0/24`.
|
||
- **`RC_ALLOWED_ORIGINS`** is for a UI deliberately served from another address.
|
||
- **Don't expose port 8081 to the internet.** Reads are not PIN protected. Publish only the public overlay and mobile profile paths through a reverse proxy or VPN.
|
||
|
||
See [docs/security-performance-audit.md](docs/security-performance-audit.md).
|
||
|
||
## Video guides
|
||
|
||
Short narrated recordings (`.mkv`, H.264/AAC), also linked from the in-app Guide:
|
||
|
||
- **Getting started:** [Connect a decoder](docs/videos/connect-decoder.mkv) · [Add drivers and cars](docs/videos/add-drivers-cars.mkv) · [Create a race](docs/videos/create-race.mkv) · [Run a session](docs/videos/run-a-session.mkv)
|
||
- **Interface tour:** [Settings tabs](docs/videos/settings-tabs.mkv) · [Event Manager tabs](docs/videos/event-manager-tabs.mkv) · [Race day schedule](docs/videos/event-schedule.mkv)
|
||
- **Race day and after:** [Sponsor event](docs/videos/sponsor-event.mkv) · [Team race](docs/videos/team-race.mkv) · [Open practice ranking](docs/videos/practice-ranking.mkv) · [Race overview and archive](docs/videos/race-overview.mkv) · [Judging: calls, penalties and DSQ](docs/videos/judging.mkv)
|
||
|
||
Recorded with `node scripts/record-video-guides.mjs`, against an isolated test server.
|
||
|
||
## Installation
|
||
|
||
RaceCore runs on 64-bit Windows 11 and Linux with Node.js 22 or 24 LTS and npm 10+. Use `npm ci` (the repository has a `package-lock.json`).
|
||
|
||
### Windows 11
|
||
|
||
1. **Git:** run `git --version`. If it's missing, run `winget install --id Git.Git --exact --source winget` and reopen PowerShell, or use [Git for Windows](https://git-scm.com/download/win). Without Git, download the ZIP from [the repository](https://git.dio.nu/Public/Live_RC) and extract all of it.
|
||
2. **Download:**
|
||
```powershell
|
||
Set-Location $HOME
|
||
git clone https://git.dio.nu/Public/Live_RC.git Live_RC
|
||
Set-Location .\Live_RC
|
||
```
|
||
3. **Install:** run `.\windows\install.bat` (or double-click it). It does the following:
|
||
- installs Node.js LTS if needed, plus the Visual C++ runtime that AMMC needs;
|
||
- runs `npm.cmd ci`;
|
||
- verifies Express, SQLite and AMMC;
|
||
- creates `data\` and `logs\`;
|
||
- starts RaceCore in the background.
|
||
4. **Check:**
|
||
```powershell
|
||
npm.cmd run status
|
||
Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"
|
||
```
|
||
Then open `http://localhost:8081`, or `http://<ipconfig address>:8081` from another computer.
|
||
|
||
Use `npm.cmd` in PowerShell; it avoids the "running scripts is disabled" error. Manual install without the script: `npm.cmd ci`, `npm.cmd run verify`, `npm.cmd start`. Don't use `--ignore-scripts`, because SQLite needs its install script.
|
||
|
||
### Linux (Ubuntu/Debian)
|
||
|
||
```bash
|
||
sudo apt update && sudo apt install -y git curl build-essential
|
||
# Node.js 22 if "node --version" is missing or older:
|
||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||
sudo apt install -y nodejs
|
||
git clone https://git.dio.nu/Public/Live_RC.git Live_RC
|
||
cd Live_RC
|
||
npm ci
|
||
npm run verify
|
||
chmod +x AMMC/linux_x86-64/ammc-*
|
||
npm start
|
||
npm run status
|
||
```
|
||
|
||
Open `http://localhost:8081`, or `http://<hostname -I address>:8081`. The bundled Linux AMMC needs **GLIBC 2.39+** (`ldd --version`). On older systems, use a matching AMMC build or run AMMC on another host; never replace the system GLIBC.
|
||
|
||
### Runtime commands
|
||
|
||
| Command (Windows: `npm.cmd ...`) | What it does |
|
||
|---|---|
|
||
| `npm start` | Start in the background |
|
||
| `npm run status` | Is it running? (PID in `data/server.pid`) |
|
||
| `npm restart` | Restart after an update |
|
||
| `npm stop` | Stop |
|
||
| `npm run start:fg` | Run in the terminal and show errors directly |
|
||
| `npm run tts:install` | Install Piper and the standard voices |
|
||
|
||
Logs go to `logs/server.out.log` and `logs/server.err.log`; data is kept in `data/`.
|
||
|
||
The `windows\` helper scripts:
|
||
- `install.bat`: install, verify and restart.
|
||
- `start_backend.bat` and `restart_backend.bat`: start or restart the server.
|
||
- `start_ammc.bat`: start AMMC.
|
||
- `start_all.bat`: start AMMC and the server, then open the browser.
|
||
- `stop_all.bat`: stop the server and AMMC.
|
||
|
||
### Update without losing data
|
||
|
||
Never delete `data/`. To update:
|
||
|
||
```bash
|
||
npm stop
|
||
git pull --ff-only
|
||
npm ci
|
||
npm run verify
|
||
npm restart
|
||
```
|
||
|
||
On Windows, use the same commands with `npm.cmd`. The menu shows when an update is available, and the update can also be run from Settings → System & backup. For a ZIP installation, keep `data/` and never copy `node_modules/` between Windows and Linux.
|
||
|
||
### Restore a server backup
|
||
|
||
Backups are in `data/backups/`. Restore is a local command, on purpose:
|
||
|
||
```bash
|
||
npm stop
|
||
npm run backup:restore -- <backup-file>.sqlite --confirm
|
||
npm start
|
||
```
|
||
|
||
On Windows, find the latest file with `Get-ChildItem .\data\backups\*.sqlite | Sort-Object LastWriteTime -Descending | Select-Object -First 1`. The restore validates the file and first takes a `pre_restore` backup of the current database.
|
||
|
||
## Decoders and AMMC
|
||
|
||
The full guide, with network diagrams, 1-4 decoder examples, firewall setup and troubleshooting, is [docs/decoder-setup.md](docs/decoder-setup.md) (Swedish: [docs/decoder-setup.sv.md](docs/decoder-setup.sv.md)).
|
||
|
||
| Role | Placement | Example decoder IP | AMMC WS port | Effect |
|
||
|---|---|---:|---:|---|
|
||
| Main | Start/finish loop | `192.168.1.10` | `9000` | Counts laps |
|
||
| Split | Intermediate loop | `192.168.1.11` | `9001` | Split time, never a lap |
|
||
| Pit entry | Pit lane entry | `192.168.1.12` | `9002` | Opens a pit stop |
|
||
| Pit exit | Pit lane exit | `192.168.1.13` | `9003` | Closes and times it |
|
||
|
||
**Managed AMMC** (Settings):
|
||
1. Enable Managed AMMC.
|
||
2. Enter the decoder IP for each channel.
|
||
3. Click **Start AMMC**, then **Use server WS URL**.
|
||
|
||
AMMC runs on the server computer, not in the browser. The bundled binaries are in `AMMC/windows64`, `AMMC/linux_x86-64` and `AMMC/apple_m`.
|
||
|
||
**Manual start:** run one `ammc-amb -w <port> <decoder-ip>` per decoder. In Settings, set the WebSocket URL (e.g. `ws://<server-ip>:9000`) and press **Connect decoder**. The browser connects to the AMMC host, not the decoder itself. On Linux with UFW, run `sudo ufw allow 8081/tcp` and `sudo ufw allow 9000:9003/tcp`.
|
||
|
||
**Diagnostics:** Settings → Decoder / socket diagnostics shows each channel's connection, frames and passings, the latest raw message and 50 events. **`ammc-sim`** emulates a decoder with chosen transponders, for training and testing without hardware.
|
||
|
||
AMMC sends PASSING messages like this ([AMMC docs](https://www.ammconverter.eu/docs/intro/quick-start/)):
|
||
|
||
```json
|
||
{ "msg": "PASSING", "passing_number": 1, "transponder": 232323, "rtc_time": "2022-10-11T22:57:36.099+02:00", "strength": 0.0, "resend": false, "loop_id": "55" }
|
||
```
|
||
|
||
### Testing without a decoder
|
||
|
||
Settings → "Decoder simulator" starts it from the UI (port 9099, the app connects by itself). From a terminal, `npm run sim` starts a decoder simulator on `ws://127.0.0.1:9000` (the app's default decoder address) that replaces AMMC and the decoder, so it also runs on a laptop without either. It sends passings with realistic lap times (about 18 s, a crash now and then) for the transponders in the active heat (sponsor heats: the cars), and follows when you switch heat. Start the heat on Race Day and the laps come in. Options: `npm run sim -- --lap 15 --spread 2 --tp 1001,1002 --port 9000`. If port 9000 is busy (AMMC running), stop AMMC or use `--port 9100` and set the decoder address to `ws://127.0.0.1:9100`.
|
||
|
||
**Test data:** `test-data/` has 12 drivers (`drivers.csv`), 4 rental cars (`cars.csv`) and 8 guest names (`sponsor-gaster.txt`). Import the CSVs under Settings → System & backup (Import drivers CSV / Import cars CSV), paste the names into a sponsor event, and run it with the simulator.
|
||
|
||
## Development and tests
|
||
|
||
- **Unit, logic and API tests:** `npm test`. The SQLite integration tests start their own server against a temporary database and never touch `data/`.
|
||
- **Browser tests:** `npm run test:browser`. They need Chrome, Chromium or Edge (set `CHROME_PATH` if it isn't found), and run against an isolated server with a fake decoder.
|
||
- **Screenshots and video guides:** `node scripts/capture-screenshots.mjs [name]` and `node scripts/record-video-guides.mjs`.
|
||
- **Docs:** the module overview is [docs/javascript-architecture.md](docs/javascript-architecture.md), and planned and finished work is in [ROADMAP.md](ROADMAP.md).
|
||
- **Auto reload:** the client reloads when `index.html` or frontend files change. After backend changes, run `npm restart`.
|
||
- **Raw data:** `/api/passings` (latest passings) and `/api/state` (app state), on the local network only.
|