"Add Windows installer and driver training rewards"

2026-08-24 14:48:49 +02:00
parent 4c0e94bc50
commit de7b4adfe0
21 changed files with 2068 additions and 210 deletions
--- a/windows/README.md
+++ b/windows/README.md
@@ -1,174 +1,169 @@
-# JMK RB Live Event
+# Windows 11 installation

-RC timing app med sponsor-eventflöde (delade bilar/transpondrar mellan olika heat/finaler), AMMC WebSocket och lokal SQLite-lagring på Windows.
+This folder contains the supported Windows 11 installation and start scripts for JMK RB RaceController.

-## Vad som ingår
- Event-lägen:
-  - `Race (driver transponders)`
-  - `Track Event (shared cars)`
- UI-separering:
-  - `Event` = sponsor-event med delade bilar/transpondrar
-  - `Race Setup` = riktiga race med personlig transponder per förare
- `Race Setup` innehåller nu även:
-  - välj exakt vilka förare som är med i racet
-  - practice-ranking
-  - kval-ranking med `poäng` eller `bästa resultat`
-  - inbyggd guide för hur man skapar race steg för steg
-  - beskrivningar direkt i alla fält under `Raceformat`
-  - sessionstyp `Free Practice` för löpande varvtider utan seedning
-  - auto-generering av kvalheat från practice-ranking eller klasslista
-  - reseeding av kommande kvalheat från aktuell ranking
-  - auto-generering av `A/B/C...` finaler från ranking
-  - sparad manuell grid per session via dragbar grid-editor
-  - final-ranking över flera leg med räknade finalheat
-  - valbar `bump-up` mellan finaler
-  - reserverade bump-platser i högre finaler
-  - visuell finalmatris med reserverade bump-platser
-  - dragbar grid-editor för positionsstart
-  - utskrift/export av heatsheets per kval/final
-  - overlay-vy för extern leaderboard-skärm
-  - flera overlay-lägen: leaderboard, speaker och results
-  - utskrift av startlistor och resultat
-  - genererade kval/finaler ärver tid och starttyp från raceformatet
-  - finish-ljud som siren i stället för browser-röst
- Sessioner: `practice`, `qualification`, `heat`, `final`
- Sponsor-verktyg:
-  - Skapa rundor automatiskt (`qualification`, `heat`, `final`)
-  - Auto-assign förare -> bil per session
- Live timing från AMMC WebSocket (`msg: "PASSING"`)
- Hanterad AMMC från webbgränssnittet:
-  - backend kan starta/stoppa lokal `ammc-amb` på Windows, Linux och macOS
-  - läser bundlade binärer från `AMMC/windows64`, `AMMC/linux_x86-64`, `AMMC/apple_m`
- Redigering i UI:
-  - Klasser, eventnamn/datum, förare och bilar kan redigeras direkt
- Live race-kontroll:
-  - Nedräkning under pågående session
-  - Auto-finish vid tidslut med status `Race is finished`
-  - Leaderboard-sortering: varv först, därefter närmast måltid för sessionen (t.ex. 5 min = 600s)
-  - Browserljud för passing (`blipp` eller tala förarnamn) och målgång
-  - Sessioninställningar för `Mass start`, `Position start`, `Staggered`
-  - `Timing` visar grid/startordning för aktiv `Position start`-session
-  - leaderboard visar både `gap till ledaren`, `gap till bilen framför` och `eget delta` mot förra varvet
-  - Practice/Kval kan seedas på bästa `2` eller `3` varv i sessionsinställningar
- Persistens:
-  - Frontend state i browser (`localStorage`)
-  - Samma state + passeringar sparas i lokal SQLite via Node-backend
- Inbyggd `Guide`-meny i appen med steg-för-steg för:
-  - Sponsor-event (10 personer / 4 bilar)
-  - Vanligt race
-  - AMMC + npm setup på Windows och Linux
- Språkval i UI: `SV` / `EN`
+## Supported runtime

-## Windows installation
-Kör i PowerShell i projektmappen.
+- 64-bit Windows 11 (`x64` or `arm64`)
+- Node.js `22` or `24` LTS
+- npm `10` or newer
+- bundled AMMC runtime in `AMMC\windows64`

-1. Installera Node.js LTS (18+).
-2. Installera dependencies:
-   ```powershell
-   npm install
-   ```
-3. Starta servern i bakgrunden:
-   ```powershell
-   npm start
-   ```
-4. Öppna:
-   - `http://localhost:8081`
-   - eller från annan dator: `http://<server-ip>:8081`
+Node.js 18 and 20 are not supported by the current native SQLite dependency.
+
+## Recommended installation
+
+1. Extract or clone the complete repository, preferably to a short path such as `C:\Live_RC`.
+2. Double-click `windows\install.bat`.
+3. Approve the Node.js LTS installation if Windows asks for it.
+4. Wait until the script reports `Windows setup completed`.
+5. Start with `windows\start_backend.bat` or `npm start`.
+6. Open `http://localhost:8081`.
+
+The installer:
+
+- checks the Windows architecture
+- checks Node.js and installs current LTS with `winget` when needed
+- installs/checks Microsoft Visual C++ 2015-2022 x64 Runtime for bundled AMMC
+- runs `npm ci` from `package-lock.json`
+- verifies that Express loads
+- opens an in-memory SQLite database through `better-sqlite3`
+- verifies `ammc-amb.exe`, `ammc.dll`, and `MyLapsSDK.dll`
+- creates `data\` and `logs\`
+
+Run from PowerShell instead when you want options:
+
+```powershell
+Set-ExecutionPolicy -Scope Process Bypass
+.\windows\setup.ps1
+```
+
+Install, add inbound firewall rules for ports `8081` and `9000`, and start the server:
+
+```powershell
+Start-Process powershell -Verb RunAs -ArgumentList '-ExecutionPolicy Bypass -File .\windows\setup.ps1 -OpenFirewall -StartServer'
+```
+
+## Manual installation
+
+Install Node.js 22 or 24 LTS, then run in the repository root:
+
+```powershell
+npm ci
+npm run verify
+npm start
+```
+
+`npm ci` installs exactly the dependency versions in `package-lock.json`. The install fails early with an actionable message if Node.js is unsupported. The post-install verification also fails if the native SQLite module cannot run.
+
+## Runtime commands

-Vanliga kommandon:
 ```powershell
 npm start
-npm stop
-npm restart
 npm run status
+npm restart
+npm stop
 npm run start:fg
 ```

- `npm start` startar `live_event` i bakgrunden
- `npm stop` stoppar processen via `data/server.pid`
- `npm restart` startar om backend
- `npm run status` visar om backend kör
- `npm run start:fg` kör i foreground för felsökning
+- `npm start` starts `server.js` in the background.
+- `npm run status` reads `data\server.pid` and reports process state.
+- `npm restart` restarts the background process.
+- `npm stop` stops it.
+- `npm run start:fg` runs in the current terminal for troubleshooting.
+- stdout is written to `logs\server.out.log`.
+- stderr is written to `logs\server.err.log`.
+- SQLite data is written to `data\rc_timing.sqlite`.

-### Windows scripts (bakgrundsstart)
-Det finns färdiga `.bat`-filer i mappen `windows/`:
- `windows\\start_ammc.bat` startar AMMC i bakgrunden
- `windows\\start_backend.bat` startar `npm start` i bakgrunden (logg: `logs\\backend.log`)
- `windows\\start_all.bat` startar både AMMC + backend och öppnar webbsidan
- `windows\\stop_all.bat` stoppar backend på port `8081` och `ammc-amb.exe`
+## Windows helper scripts

-SQLite-filen skapas automatiskt här:
- `data\\rc_timing.sqlite`
+- `windows\install.bat`: install and verify all runtime dependencies
+- `windows\start_backend.bat`: start the Node backend in the background
+- `windows\start_ammc.bat`: start bundled AMMC manually
+- `windows\start_all.bat`: start AMMC, backend, and open the browser
+- `windows\stop_all.bat`: stop the backend and `ammc-amb.exe`

-## Koppla mot AMMC
-Det finns nu två sätt:
+Manual AMMC start with a decoder IP:

-### A. Hanterad AMMC i webbgränssnittet
-Viktigt:
- AMMC körs på samma host där `npm start` / `node server.js` körs.
- Om du öppnar sidan från en annan laptop startas ingen AMMC där.
- Fältet `AMMC binär` i `Settings` är en sökväg på backend-hosten, inte på klienten som surfar in.
+```bat
+windows\start_ammc.bat 192.168.1.10
+```

-1. Lägg AMMC-binärerna i projektmappen `AMMC/` (redan gjort i denna repo).
-2. Öppna `Settings`.
-3. Aktivera `Hanterad AMMC / Managed AMMC`.
-4. Sätt `Decoder IP / host`, kontrollera port `9000`, spara.
-5. Klicka `Starta AMMC / Start AMMC`.
-6. Klicka `Använd serverns WS-url / Use server WS URL` så sätts klienten till t.ex. `ws://<server-ip>:9000`.
+The script resolves the executable to:

-Standardbinärer:
- Linux-host: `AMMC/linux_x86-64/ammc-amb`
- Windows-host: `AMMC/windows64/ammc-amb.exe`
- macOS-host: `AMMC/apple_m/ammc-amb`
+```text
+AMMC\windows64\ammc-amb.exe
+```
+
+You can override its defaults before starting:
+
+```bat
+set DECODER_IP=192.168.1.10
+set WS_PORT=9000
+windows\start_ammc.bat
+```
+
+## Managed AMMC from the web UI
+
+The recommended normal operation is to let the backend manage AMMC:
+
+1. Start RaceController with `npm start`.
+2. Open `Settings`.
+3. Enable `Managed AMMC`.
+4. Set the decoder IP and WebSocket port `9000`.
+5. Save and click `Start AMMC`.
+6. Use the server WebSocket URL and connect the decoder.
+
+AMMC always runs on the computer that runs `npm start`. Opening the UI from a laptop does not start AMMC on that laptop.
+
+## Network access
+
+- Admin/UI/backend: TCP `8081`
+- AMMC WebSocket: TCP `9000`
+
+Find the Windows server address with:

-### B. Manuell start
-Starta AMMC med WebSocket (exempel):
 ```powershell
-ammc-amb.exe -w 9000 192.168.1.11
+ipconfig
 ```

-I appen:
-1. `Settings`
-2. Sätt `WebSocket URL` till t.ex. `ws://127.0.0.1:9000`
-3. Sätt `Backend URL` till `http://127.0.0.1:8081`
-4. Klicka `Test Backend`
-5. Gå till `Timing` och klicka `Connect Decoder`
+Then open this from another computer on the LAN:

-Om du kör Linux-brandvägg (UFW), öppna porten:
-```bash
-sudo ufw allow 8081/tcp
+```text
+http://<windows-server-ip>:8081
 ```

-## Auto reload vid uppdatering
- Servern bevakar `index.html`, `src/app.js` och `src/styles.css`.
- När du uppdaterar filer i `live_event` och sparar, laddar klienten om sidan automatiskt.
- Om backendkoden ändras, kör `npm restart`.
+Do not expose the full admin UI directly to the internet. Publish only `/public-overlay/*` through a reverse proxy when an external overlay is needed.

-## Verifiera att SQLite sparar
-Hämta senaste passeringar via API:
- `http://localhost:8081/api/passings`
+## Native dependency troubleshooting

-Hämta sparad app-state:
- `http://localhost:8081/api/state`
+`better-sqlite3` normally installs a prebuilt Windows binary and does not require Visual Studio. If npm falls back to compiling it:

-## Viktig regel för sponsor-event
- I **samma pågående session** måste varje aktiv bil ha unikt transponder-ID.
- Samma transponder-ID kan återanvändas i **nästa session** (Heat 1 -> Heat 2 -> Heat 3 -> Final 1 ...).
+1. Confirm `node --version` reports Node 22 or 24.
+2. Move the repository to a short ASCII path such as `C:\Live_RC`.
+3. Run the Node native-tools installer as Administrator:

-## Referens AMMC JSON
-Officiell quick-start:
- https://www.ammconverter.eu/docs/intro/quick-start/
-
-Exempelmeddelande:
-```json
-{
-  "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"
-}
+```powershell
+& "C:\Program Files\nodejs\install_tools.bat"
 ```
+
+4. Reopen PowerShell and run:
+
+```powershell
+npm ci
+npm run verify
+```
+
+## Update an existing installation
+
+Stop the service, update the files, reinstall locked dependencies, verify, and restart:
+
+```powershell
+npm stop
+git pull
+npm ci
+npm run verify
+npm start
+```
+
+Keep `data\` when updating. It contains the SQLite database, saved state, PID file, and local AMMC configuration.