# Windows 11 installation

This folder contains the supported Windows 11 installation and start scripts for JMK RB RaceController.

## Supported runtime

- 64-bit Windows 11 (`x64` or `arm64`)
- Node.js `22` or `24` LTS
- npm `10` or newer
- bundled AMMC runtime in `AMMC\windows64`

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. The installer runs `npm.cmd restart`, leaving the backend running in the background.
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.cmd 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\`
- runs `npm.cmd restart` so both new installations and updates use the installed code immediately

Run from PowerShell instead when you want options:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\windows\setup.ps1
```

Install, add inbound firewall rules for `8081` and decoder channels `9000-9003`, 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.cmd ci
npm.cmd run verify
npm.cmd start
```

`npm.cmd 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.

The project intentionally uses `better-sqlite3` v12.11.x. That release provides a working prebuilt Windows binary for the supported Node.js versions. The package is explicitly listed in `allowScripts` so npm 12 may run its binary installer; do not use `npm.cmd ci --ignore-scripts`.

Use `npm.cmd` from PowerShell when local execution policy blocks `npm.ps1`. The plain `npm` command works normally from Command Prompt (`cmd.exe`).

## Runtime commands

```powershell
npm.cmd start
npm.cmd run status
npm.cmd restart
npm.cmd stop
npm.cmd run start:fg
```

- `npm.cmd start` starts `server.js` in the background.
- `npm.cmd run status` reads `data\server.pid` and reports process state.
- `npm.cmd restart` restarts the background process.
- `npm.cmd stop` stops it.
- `npm.cmd 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 helper scripts

- `windows\install.bat`: install, verify, and restart the backend
- `windows\start_backend.bat`: start the Node backend in the background
- `windows\restart_backend.bat`: restart the Node backend after copied or pulled updates
- `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`

Manual AMMC start with a decoder IP:

```bat
windows\start_ammc.bat 192.168.1.10
```

The script resolves the executable to:

```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.cmd start`.
2. Open `Settings`.
3. Enable `Managed AMMC`.
4. Set the Main decoder IP and WebSocket port `9000`.
5. Optionally enable Split (`9001`) and Pit entry/exit (`9002`/`9003`) with the IP address of each physical decoder.
6. Save and click `Start AMMC`.
7. Use the server WebSocket URLs and connect the decoders.

AMMC always runs on the computer that runs `npm.cmd start`. Opening the UI from a laptop does not start AMMC on that laptop.

## Network access

- Admin/UI/backend: TCP `8081`
- Main AMMC WebSocket: TCP `9000`
- Optional Split/Pit AMMC WebSockets: TCP `9001-9003`

Each physical decoder has its own IP. Each AMMC process on the Windows backend has its own WebSocket port. Main is the only channel that counts laps; Split records intermediate times, while Pit entry and Pit exit open and close a timed pit stop.

Find the Windows server address with:

```powershell
ipconfig
```

Then open this from another computer on the LAN:

```text
http://<windows-server-ip>:8081
```

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.

## Native dependency troubleshooting

`better-sqlite3` normally installs a prebuilt Windows binary and does not require Visual Studio. If npm falls back to compiling it:

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:

```powershell
& "C:\Program Files\nodejs\install_tools.bat"
```

4. Reopen PowerShell and run:

```powershell
npm.cmd ci
npm.cmd run verify
```

## Update an existing installation

Stop the service, update the files, reinstall locked dependencies, verify, and restart:

```powershell
npm.cmd stop
git pull
npm.cmd ci
npm.cmd run verify
npm.cmd restart
```

Keep `data\` when updating. It contains the SQLite database, saved state, PID file, and local AMMC configuration.