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 · Changes: CHANGELOG.md · Plans: ROADMAP.md · The running version is shown at the bottom of the menu.
Contents
- Highlights
- Screenshots
- Quick start
- Using RaceCore
- Video guides
- Installation
- Decoders and AMMC
- 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.
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 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).
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.
-
Name and classes.
-
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.
-
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.
-
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.
- Classes: create a class called Rookie, with no drivers of its own.
- Single race: in Race Setup, create the race with class Rookie and tick the rookies under Participants → Drivers from other classes.
- 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.
- 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.jsand/src/public_training.css. Ready-made Teltonika files are inscripts/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: setPUBLIC_OVERLAY_TOKENand 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:
- 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.
- Cars: tick the cars, or add one with name and transponder.
- 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.
- 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.
- 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.
- Everything is stored in
- Backups:
- automatic before every session start, plus manual ones;
- the latest 30 are listed under Settings;
- restore with
npm run backup:restore(see Installation).
- 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):
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. In the race wizard, 🏠 Fetch from House of RC picks a House of RC event and fills in the name, date, class and entered drivers (existing drivers keep their transponders). Posting results back is being built together with House of RC (see ROADMAP.md).
RC_ADMIN_ALLOWED_CIDRSrestricts admin changes to certain addresses or networks, e.g.192.168.1.0/24.RC_ALLOWED_ORIGINSis 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:
- Getting started: Connect a decoder · Add drivers and cars · Create a race · Run a session
- Interface tour: Settings tabs · Event Manager tabs · Race day schedule
- Race day and after: Sponsor event · Team race · Open practice ranking · Race overview and archive · Judging: calls, penalties and DSQ
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
- Git: run
git --version. If it's missing, runwinget install --id Git.Git --exact --source wingetand reopen PowerShell, or use Git for Windows. Without Git, download the ZIP from the repository and extract all of it. - Download:
Set-Location $HOME git clone https://git.dio.nu/Public/Live_RC.git Live_RC Set-Location .\Live_RC - 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\andlogs\; - starts RaceCore in the background.
- Check:
Then open
npm.cmd run status Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"http://localhost:8081, orhttp://<ipconfig address>:8081from 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.batandrestart_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):
- Enable Managed AMMC.
- Enter the decoder IP for each channel.
- 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. 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 touchdata/. - Browser tests:
npm run test:browser. They need Chrome, Chromium or Edge (setCHROME_PATHif it isn't found), and run against an isolated server with a fake decoder. - Screenshots and video guides:
node scripts/capture-screenshots.mjs [name]andnode 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.htmlor frontend files change. After backend changes, runnpm restart. - Raw data:
/api/passings(latest passings) and/api/state(app state), on the local network only.













