Files
Live_RC/README.md
T

53 KiB
Raw Blame History

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 (fonts, flags and sounds are in the repo).

Swedish version: README.sv.md · Changes: CHANGELOG.md · Plans: ROADMAP.md · License: AGPL-3.0 · The running version is shown at the bottom of the menu.

Contents

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.

Dashboard with active session
Dashboard with active session
Race Setup wizard
Race Setup wizard
Full live overlay
Full live overlay
Leaderboard overlay
Leaderboard overlay
Practice statistics overview
Practice statistics overview
Detailed practice statistics with pace heatmap and stint analysis
Detailed practice statistics
Series / cup with numbered steps
Series / cup
Judging and race corrections
Judging and race corrections
Race sounds and announcements
Race sounds and announcements
Event Manager's Live & results tab
Event Manager's Live & results tab
Decoder configuration
Decoder configuration
Managed AMMC configuration
Managed AMMC configuration
In-app setup guide
In-app setup guide
Race Day with quick actions during a running practice
Race Day

Quick start

Windows 11 (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:

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 walk through the first decoder connection, drivers and the first race. Full steps: 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, the break between heats, a longer break between rounds (practice → qualifying, round 1 → round 2) and a break before the finals (lunch, counted from the end of qualifying, so the finals don't start the moment they are created). ☕ on a heat adds an extra break before it. Fixed breaks at clock times (e.g. Lunch 12:00–13:00 and Prize-giving 16:00–16:30; + Add break for more, ✕ removes one) keep every heat out of those times: a heat that would start or run into a break starts when it ends, and the printed running order and the drivers' board show the break. Empty round/finals breaks use the heat break. Marshals (Off / Drivers of the heat before / Drivers of the heat after) shows who marshals each heat in the schedule, the printout and the drivers' board ("🦺 Marshals: …"), and the heat call reads them after the drivers; a driver in the heat itself never marshals it. ▲▼ 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. With several classes on one day, every class's heats run in the same order. Finals are never created automatically: when a class's qualifying is done it says "Waiting: check qualifying and press 🏁 Create finals for …" with the class names, so qualifying can be corrected first. Then the autopilot runs the finals. 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, finals on top (A final first), then qualifying, then practice. A finished heat or final has its own 🖨 and PDF buttons for just that heat, e.g. for the board in the pits.
    • 📈 Lap chart: every qualifying heat and final has a fold-out lap chart - each driver's place after every lap as a coloured line, place 1 on top, names at their official finish place. Counted from the passings, nothing extra to set up. It is printed and in the PDF of a single heat, and with the finals in the full results.
  • 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.
  • Check-in (optional): Manage race → Check-in ticks ✓ Present and 💰 Paid per driver, with search and a count ("12 of 15 checked in"). 📡 turns green once the driver's transponder has crossed the decoder today (on the computer running the decoder). Remove no-shows takes drivers not checked in out of the race and heats not yet run, after asking and only before qualifying starts; they stay in the drivers' register. Print list gives a sheet to tick off at the gate. Without a check-in everyone counts as present and nothing else in the race changes.
  • Decoder alarm: when the decoder disconnects during a heat (or its count-down), a red banner shows at the top of every page, "Decoder disconnected at 12:03 – laps are not being recorded", with Reconnect and Silence, and a warning sounds every 30 s. In qualifying, heats and finals it also alarms when the decoder is connected but no passing has come for 30 s (or three of the fastest laps), for example when the decoder box or loop has stopped working. Practice only alarms on a dropped link. When the decoder works again, the banner shows for 10 s how long timing was down, so the laps can be checked in Judging. It runs on the Race Controller Master computer and can be turned off under Settings → Audio → Decoder alarm during heats.
  • 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).

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). Changing it afterwards, e.g. from best 3 laps to laps and time, also re-ranks the qualifiers already run (results are worked out from the laps); a changed heat time only reaches heats not run yet. Finals already created are not redrawn;
    • 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, ÖRC Winter, endurance, and whole race days in federation style - EFRA 1/10 Off-road, EFRA 1/10 Touring / On-road, EFRA/SBF 1/8 Nitro (bump-up, long final), IFMAR worlds, ROAR (timed qualifying, bump-up, single A main), Quick club day, Rookie / Junior and Points race without finals - or your own saved club presets. A federation preset also sets the practice rounds (with seeding on the best 3 laps in a row), and its description is shown under the choice. The values follow the handbooks in spirit; rules change between editions, so everything stays editable;
    • 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;
      • practice is split into heats the same way, and ranked by Practice seeding at the top of Format (0 = best single lap; EFRA presets: 3 fastest laps in a row). Lists and overlay show the seeding time, and a better seeding time is called out ("new seeding time, 0.40 quicker"). Open Practice is not affected;
      • changing cars per heat or the number of qualifying rounds under Format rebuilds the practice and qualifying heats that have not run yet;
      • Manage → Race actions shows the buttons in the order of the day: 1. after practice, Generate qualifying from practice; 2. between qualifying rounds (optional), Regroup qualifying heats not run yet; 3. after qualifying, Generate finals from qualifying and bump-ups. Until qualifying is built from practice, the heat list says the qualifying heats are preliminary; 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 start time and gap here are the same setting as First start and Break between heats in Race Day for the race's date, and the times shown are Race Day's (breaks and lunch included).

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.
    • 🔗 Link to driver: when one driver shows on two rows (results left on a deleted duplicate) the row gets a picker - choose the right driver and the rows are merged.
    • 📄 on a round that has run downloads the day's CSV for that class (see Data, backups and import/export).
    • 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. The driver list is grouped by class (Rookie 2WD, Rookie 4WD, Junior 4WD ...): each class has All and None, the search box finds a driver by name or transponder, Show only selected checks the list, and Same drivers as… copies the field of an earlier race (the series' own rounds first). Select all takes only the race's own class (or what the search shows), never the whole club.
  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 and tick the rookies class by class (same grouped list). Copy from previous takes the same rookies next time, from every class.

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.

Club practice overview (bottom of Training stats): search for a driver, pick one class, Only drivers who trained (on by default) and Group by class. Click a column heading to sort.

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;
    • practice stints that fold out to every lap time: laps, best, average, total time and spread per stint; the stint's fastest lap green, the day's fastest purple, slow laps red and the out lap after a break marked;
    • 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.
    • 🏁 My race today: on a race day the profile shows, on top, the driver's next heats with their time (as on Race Day, breaks and delays included) and grid place in finals, marshal duties, and results of today's heats. The race controller computer sends today's schedule to the server every 15 s (driver ids only, no names), so no new link or router change is needed. No card on days without racing.
  • A Standard / Pro switch at the top. Pro is a clean practice view without goals or settings: today's laps, stints, driving time, best, average and personal best, then the stint cards that fold out to every lap. The choice is remembered on the phone and can be linked with ?mode=pro.
  • 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. The lap time call can be turned on for races too: Lap time at each passing → Practice and races under Settings → Audio or on the speaker panel.
  • Times in announcements (personal best, fastest lap, track record) are said as a speaker does: seconds and hundredths, "18 sixty-three" / "18 sextiotre", and "18 flat" on .00.
  • 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; only New leader in practice can be turned off (in Settings and the Race Day sound panel), since nobody races anyone there.
  • Heat call and staggered start: Auto (default) calls car numbers in finals ("Car 1, 2, 3") and names elsewhere; or choose Names, Car numbers, or Car number + name ("car 5 Anders"). The car number is the grid slot. A staggered start calls each car 3 s apart.
  • Local neural voice (Piper, recommended): 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.
    • Press Pre-generate phrases and driver names before race day, and again after adding drivers or changing a pronunciation name, voice or speed. Lines that already exist are skipped. A name that is not pre-generated is made the first time it is said, and if that takes too long the browser voice reads it that one time.
    • 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, last lap, result, best, gap, and places since the start (▲/▼ in heats and finals).
  • Last lap changes at every passing. In Open Practice, where the result is just the best lap, the leaderboard shows the last lap instead of the result.
  • A session ranked on the best N laps (Open Practice on N laps in a row or X minutes, or a practice or qualifier seeded on the best N laps) shows only what the rule ranks on, the same in every session type: position, driver, result (for example "3 laps 55.123"), gap and best lap (the next-lap bar stays). Heats on laps and time, like most qualifiers and every final, keep the full columns.
  • 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 clear 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.
  • Live marks in the leaderboard and the TV tower: a driver's row flashes briefly on a new time, a fuel pump badge with a ticking clock shows while the car is in the pits (then the stop time for 5 s), and a new split shows for 4 s with ± against the previous one. They run on the overlay computer's clock, and a freshly opened overlay never flashes every row.
  • The TV title plate has the RaceCore look: the club logo or a red RC mark, the event in small capitals and the heat in Barlow (a soft font; overlays use it instead of the app's squared Orbitron).
  • 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.
  • Size (50-150 %) makes the OBS graphics smaller or larger to fit the stream; the TV tower, plate and every OBS layout scale together.
  • Copy OBS URL gives a browser-source link; the chosen columns and the size are part of the link (?scale=80), so two streams can use different sizes.
  • 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.

Driver register

  • Drivers lists every driver grouped per class (folds open and closed; untick Group by class for one list).
  • Search on name, transponder, brand, club or country, Class to show just one class, and Sort by name, class, club, transponder or brand (↑/↓ reverses). Sort and grouping are remembered in the browser.
  • Country (optional): pick from the list or type it ("Sweden", "SE" and "SWE" work too). The driver then gets a small flag before the name in timing, Race Day, the overlay and OBS, start lists, results, printouts and PDFs. No country, no flag. The flags are in the repo (src/flags), so they work offline. OBS can turn them off under Show flags.
  • Select drivers with the boxes (or Select all shown) and Delete selected; a confirm names them first. Deleting, one or many, also removes the drivers from every heat, participant list and team.
  • Merge with another driver (edit the driver): the same person entered twice. Every heat, lap, result, entry, check-in, series point and training lap moves to the driver you keep, and the duplicate is removed. Only the Race Controller Master can merge.
  • The same transponder twice in one class is refused (the decoder can't tell the laps apart). The same person in another class is fine - the lap goes to the driver who is in the running 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).
  • Results as PDF automatically (Settings → Appearance & overlay → Save results as PDF automatically: Off / Every heat / Final results only):
    • The race controller computer saves the result 10 s after the finish in data/results/<date>/. After the last final the full results are saved too. A correction in Judging saves the file again.
    • Race Day shows "📄 Result saved", and the Results archive has the list 📄 Saved PDFs. The files are not part of the server backup (that covers the database), so copy the folder to keep them long term.
    • Ask to print when the finals are done shows a 🖨 Print results button when the last final is done. A browser cannot print without a click; for fully automatic printing start Chrome with --kiosk-printing, which prints straight to the default printer when the button is pressed.
  • Export/import (Settings → Storage):
    • 📄 CSV for the race day (Results archive: pick the same date in From and To, and a class or all): first a summary per heat (place, laps, total time, best and average lap), then every lap in running order with transponder, lap time, time of day and whether the lap counted. Semicolons and UTF-8 with BOM, so Excel opens it in columns. Every series round that has run has a 📄 shortcut.
    • 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):

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. Other computers can't change the race by mistake: when they save (pick a heat to look at, or hold an old copy) the server keeps the master's active heat, each heat's status and clock, the laps and the heats that have run. A run heat only goes back to Ready through Reset. Qualifying and finals that have run are never made again by mistake - Clear generated ... names the run heats and asks first.
  • 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. Only drivers entered on House of RC (with their own account) get results there; others are listed as not sent. Tick Send heats automatically and the race controller sends heats and qualifying after every heat by itself (semi-live), retrying without internet; the final placings are always sent by hand.
  • 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.

Video guides

Short narrated recordings (.mkv, H.264/AAC), also linked from the in-app Guide:

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. Without Git, download the ZIP from the repository and extract all of it.
  2. Download:
    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:
    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)

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:

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:

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 (Swedish: 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):

{ "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. No real transponders are needed: add a few drivers under Directory → Drivers with made-up transponder numbers (for example 2001, 2002, 2003) and put them in a heat. Real names and transponder numbers work just as well, and then everything is ready for race day. 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, and planned and finished work is in 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.

License

Copyright (C) 2026 RC RaceCore

RC RaceCore is free software: you can use, change and share it under the GNU Affero General Public License v3.0 or (at your option) any later version. If you share a changed version, or run one as a service that other people use over a network, you must make your source code available under the same license. Clubs that run RaceCore, with or without their own changes, for their own racing need to do nothing. RaceCore comes with no warranty.

Third-party parts keep their own licenses: AMMC (AMMC/LICENCE, MIT), country flags from flag-icons (MIT, see src/flags/), the fonts Barlow, Barlow Condensed and Orbitron (SIL Open Font License) and the npm packages (see each package). Piper voices are downloaded during install and have their own licenses.