JMK RB RaceController

English README. Swedish version: README.sv.md

JMK RB RaceController is an RC timing and race-control system with support for sponsor events with shared cars/transponders, AMMC WebSocket input, and local persistence through SQLite.

Screenshots

Overview

Timing

Overlay

Event

Race Setup

Team Overlay

Judging

Public Overlay And OBS

The app now supports a dedicated public overlay route so you do not need to expose the full admin UI externally.

• Public overlay route: /public-overlay/<mode>
• OBS mode: /public-overlay/obs
• OBS overlay can be configured from the Overlay menu:
  • rows
  • layout: leaderboard, grid, lowerthird
  • theme: panel, transparent, chroma
  • visible columns and blocks
• Use Copy OBS URL to generate a ready-to-paste browser-source link for OBS.

If you want simple protection for public overlays, set this environment variable on the server:

PUBLIC_OVERLAY_TOKEN=your-secret-token

Then the public overlay URL must include:

/public-overlay/obs?token=your-secret-token

Recommended deployment:

• publish only /public-overlay/* through your reverse proxy
• keep the main app/admin UI internal

Features

• Event modes:
  • Race (driver transponders)
  • Track Event (shared cars)
• UI separation:
  • Event = sponsor events with shared cars/transponders
  • Race Setup = competition races with personal driver transponders
• Storage/import tools:
  • full race-data export/import for backup or moving to another machine
  • directory export/import for only classes, drivers and cars
  • CSV export for drivers and cars when you want simple spreadsheet lists
  • single race-package export/import from Race Setup -> Manage -> Race Actions
• Race Setup includes:
  • grouped Participants and Teams sections in Manage
  • a four-step Create Race Wizard for new races
  • Manage split into Setup, Format, Generation, and Live / results
  • Basic mode now reacts to the selected preset, including a cleaner endurance view
  • Basic / Advanced mode for Race Format
  • a right-side race summary card
  • a preset-aware summary card that changes between endurance and normal race focus
  • status badges for Setup, Format, Generation, and Live / results
  • summary warnings when participants, sessions, teams, or lap-window settings are missing
  • clickable summary warnings that jump to the relevant Manage section
  • clickable step cards that act as quick navigation inside Manage
  • compact step cards with live counters such as drivers, teams, sessions, and active/results state
  • separate Race actions for generation, reseeding and bump-up
  • reorganized in-app Guide with overview cards and two-column sections
  • explicit race participant selection
  • practice standings
  • qualifying standings with points or best result
  • built-in step-by-step guide
  • inline descriptions for all Race Format fields
  • Follow-up time after scheduled race time before a heat fully closes
  • Min lap time and Max lap time filtering for shortcuts/false hits and better stint/stat logic
  • seeding modes for practice/qualifying: best N laps total, average, or consecutive
  • selectable qualifying points tables and tie-break rules
  • Race Format presets for short technical tracks, club races, IFMAR-style layouts, and endurance
  • schedule drift on Dashboard between planned and actual runtime
  • session type Free Practice for rolling lap-time display without seeding
  • automatic qualifying heat generation from practice standings or class list
  • re-seeding of upcoming qualifying heats from current standings
  • automatic A/B/C... finals generation from rankings
  • persistent manual grid per session with drag-and-drop grid editor
  • auto-reseed skips heats with locked manual grid
  • explicit Lock/Unlock grid per session
  • multi-leg final standings with counted final legs
  • optional bump-up between finals
  • reserved bump-up slots in higher finals
  • visual finals matrix with reserved bump slots
  • drag-and-drop grid editor for position starts
  • print/export of heat sheets per qualifying/final
  • overlay modes for external display screens
  • multiple overlay modes: leaderboard, speaker, results, TV, team
  • speaker overlay with event markers and separate speaker cues
  • live speaker panel in Timing
  • speaker cues and club/PDF branding from Settings
  • overlay logo upload from Settings
  • per-event/per-race branding in Manage
  • extra speaker cues for session start, new best lap, and top 3 change
  • selectable PDF themes: classic, minimal, motorsport
  • branded print and PDF exports
  • server-generated PDF exports with embedded logo
  • generated qualifying/finals inherit duration and start mode from race format
  • finish sound uses a siren instead of browser TTS
• Sessions:
  • practice
  • qualification
  • heat
  • final
  • free_practice
  • open_practice
  • team_race
• Sponsor event tools:
  • automatic round creation (qualification, heat, final)
  • auto-assign driver -> car per session
• Live timing from AMMC WebSocket (msg: "PASSING")
• Managed AMMC from the web UI:
  • backend can start/stop local ammc-amb on Windows, Linux, and macOS
  • bundled binaries from AMMC/windows64, AMMC/linux_x86-64, AMMC/apple_m
• Editing in UI:
  • classes, event names/dates, drivers, and cars can be edited directly
  • drivers and cars support optional brand fields for team, sponsor, manufacturer, or model data
  • Drivers and Cars can be searched by name, transponder, or brand directly in the UI
  • race start lists and heat sheets include driver brand in print, CSV, and PDF exports
• Live race control:
  • countdown during timed sessions
  • auto-finish at end of session time with Race is finished
  • leaderboard sorting by laps first, then nearest to target time when applicable
  • browser audio for passings (beep or driver name) and finish
  • session start types: Mass start, Position start, Staggered
  • Timing shows grid/order for the active Position start session
  • leaderboard shows gap to leader, gap ahead, and own delta
  • Recent Passings shows invalid laps such as Short lap and Over max lap
  • manual corrections in Timing -> Details: +1/-1 lap, +1/+5/-1 sec, reset
  • practice/qualifying seeding on best 2 or 3 laps
• Persistence:
  • frontend state in browser localStorage
  • same state and passings persisted to local SQLite through the Node backend
• Built-in Guide page in the app covering:
  • sponsor events (for example 10 drivers / 4 cars)
  • standard race setup
  • invalid laps, follow-up, and manual corrections
  • AMMC + npm setup on Windows and Linux
• UI language selection:
  • SV
  • EN

Create Race Wizard

• Race Setup now starts with a four-step wizard for new races:
  • Basics
  • Participants
  • Session plan
  • Confirm
• The wizard is intended to create the first race structure quickly:
  • choose class and preset
  • scope valid race drivers
  • create practice, qualifying, and/or team-race sessions automatically
• Finals are still generated later from Race Actions after practice or qualifying is complete.

Manage workflow

• After the race is created, Manage is split into four clear stages:
  • Setup
  • Format
  • Generation
  • Live / results
• Setup handles race participants and teams. The top step cards also act as quick navigation between the four blocks.
• Format handles practice/qualifying, finals, validation, presets, and advanced settings. In Basic mode, endurance hides most qualifying/finals fields until Advanced is opened.
• Generation is kept separate so actions like qualifying generation, reseeding, finals generation, and bump-up do not clutter the format form.
• Live / results is where grid, standings, print, PDF, and finals matrix are used once the structure is ready.

Export / Import

• Settings -> Storage now supports:
  • full JSON export/import for the complete competition database
  • directory JSON export/import for only classes, drivers, and cars
  • CSV export for drivers and cars
• Race Setup -> Manage -> Race Actions now supports single race packages:
  • export one race with its sessions, results, and referenced classes/drivers/cars
  • import that package into another installation as a new race entry
• JSON export files now include export metadata and a schema version field so future imports can be handled more safely.

Race features

Follow-up time

• Configure it in Race Setup -> Manage -> Race Format
• It can also be set per session when creating or editing a session
• When scheduled time ends, the session enters follow-up first
• When follow-up ends, the session closes automatically
• Generated qualifying/finals inherit follow-up from race format

Min / Max lap time

• Configure it in Race Setup -> Manage -> Race Format
• Min lap time:
  • laps faster than the threshold are ignored as shortcuts or false hits
• Max lap time:
  • laps slower than the threshold are not counted as valid laps
  • also used to split stints and improve statistics

Example:

• track around 16 sec/lap
• Min lap time = 11 sec
• Max lap time = 60 sec

Invalid passings

• Timing -> Recent Passings shows both valid and invalid passings
• displayed statuses include:
  • Short lap
  • Over max lap
• invalid passings are visually highlighted

Manual corrections

• open Timing
• click Details on a driver or team
• available actions:
  • +1 lap
  • -1 lap
  • +1 sec
  • +5 sec
  • -1 sec
  • Reset correction
• leaderboard and results update immediately

Best laps / average / consecutive

• Configure per session with Seed Method when Best laps for seeding is greater than 0
• available modes:
  • Best N laps, total
  • Best N laps, average
  • Best N consecutive laps
• leaderboard and standings use the correct format:
  • total: 3/00:48.321
  • average: 3 avg 16.107
  • consecutive: 3 con 00:49.005

Points tables and tie-break

• Configure in Race Setup -> Manage -> Race Format
• qualifying points tables:
  • Placement values (1,2,3...)
  • Descending by field size
  • 10-9-8-7-6-5-4-3-2-1
• qualifying tie-break options:
  • Compare counted rounds
  • Best single lap
  • Best round / heat result
• qualifying standings also show an inline tie-break note in the table

Race format presets

• Race Setup -> Manage -> Race Format
• choose a preset and click Apply preset
• built-in presets:
  • Short technical track 16s
  • Club race qual + finals
  • IFMAR-style qual/finals
  • Endurance / team race
• after applying, all fields can still be adjusted manually and saved as usual
• Save club preset stores your own local presets in app state
• Delete club preset removes a local preset
• Settings -> Club presets can export/import the preset library as JSON between installations

Schedule drift on Dashboard

• Dashboard shows whether the day is ahead of or behind schedule
• planned time includes:
  • session duration
  • follow-up time
• actual time includes:
  • real time from start to stop
  • or live runtime if the session is still running

Invalid-lap marker in leaderboard

• if the latest passing for a driver or team is invalid, the row is marked in both leaderboard and overlay
• this makes it easier to see problems without staying in Recent Passings

Manual invalidate / restore last lap

• Timing -> Details
• Invalidate last lap marks the latest counted lap as manually invalid
• leaderboard, overlay, and lap history update immediately
• Restore latest manually invalidated lap puts the latest manually invalidated lap back if needed

Judging view

• separate Judging menu
• shows active session, leaderboard, lap history, and judging log in one view
• same corrections as Timing -> Details
• row filters:
  • All
  • Invalid
  • Corrected
  • Team race
• judging log can be exported per session as JSON
• supports Undo latest and per-log-row undo for multiple recent manual actions

Windows installation

Run in PowerShell in the project directory.

1. Install Node.js LTS (18+).
2. Install dependencies:

   npm install
   

3. Start the server in the background:

   npm start
   

4. Open:

• http://localhost:8081
• or from another computer: http://<server-ip>:8081

Common commands:

npm start
npm stop
npm restart
npm run status
npm run start:fg

• npm start starts the backend in the background
• npm stop stops the process via data/server.pid
• npm restart restarts the backend
• npm run status shows whether the backend is running
• npm run start:fg runs in foreground for troubleshooting

Windows scripts

The windows/ folder includes:

• windows\\start_ammc.bat starts AMMC in the background
• windows\\start_backend.bat starts npm start in the background (log: logs\\backend.log)
• windows\\start_all.bat starts both AMMC + backend and opens the web page
• windows\\stop_all.bat stops the backend on port 8081 and ammc-amb.exe

SQLite database file:

• data\\rc_timing.sqlite

Connect to AMMC

There are two supported modes.

A. Managed AMMC from the web UI

Important:

• AMMC runs on the same host where npm start / node server.js runs
• if you only browse from another laptop, no process starts there
• the AMMC executable field in Settings is a path on the backend host, not the client browser machine

1. Place AMMC binaries in the AMMC/ project folder.
2. Open Settings.
3. Enable Managed AMMC.
4. Set Decoder IP / host, verify port 9000, save.
5. Click Start AMMC.
6. Click Use server WS URL so the client uses for example ws://<server-ip>:9000.

Default binaries:

• Linux host: AMMC/linux_x86-64/ammc-amb
• Windows host: AMMC/windows64/ammc-amb.exe
• macOS host: AMMC/apple_m/ammc-amb

B. Manual start

Example:

ammc-amb.exe -w 9000 192.168.1.11

In the app:

1. Open Settings
2. Set WebSocket URL, for example ws://127.0.0.1:9000
3. Set Backend URL to http://127.0.0.1:8081
4. Click Test Backend
5. Go to Timing and click Connect Decoder

If Linux firewall/UFW is enabled:

sudo ufw allow 8081/tcp

Auto reload during development

• The server watches index.html, src/app.js, and src/styles.css
• When files in Live_RC change, the client reloads automatically
• If backend code changes, run npm restart

Verify SQLite persistence

Latest passings via API:

• http://localhost:8081/api/passings

Saved app state via API:

• http://localhost:8081/api/state

Important rule for sponsor events

• In the same running session, every active car must have a unique transponder ID
• The same transponder ID can be reused in the next session (Heat 1 -> Heat 2 -> Heat 3 -> Final 1 ...)

AMMC JSON reference

Official quick start:

• https://www.ammconverter.eu/docs/intro/quick-start/

Example message:

{
  "msg": "PASSING",
  "passing_number": 1,
  "transponder": 232323,
  "rtc_time": "2022-10-11T22:57:36.099+02:00",
  "strength": 0.0,
  "resend": false,
  "tran_code": "ID:232323",
  "loop_id": "55"
}