Live_RC/docs/decoder-setup.md

Decoder, IP, and AMMC configuration

This guide explains how physical MyLaps/AMB decoders connect to JMK RB RaceController. It uses this example network:

Device	Example address	Purpose
RaceController/backend	192.168.1.100	Runs Node.js, AMMC processes, web UI, and API
Operator laptop	192.168.1.50	Opens the web UI; does not run AMMC
Main decoder	192.168.1.10	Start/finish and lap counting
Split decoder	192.168.1.11	Optional intermediate timing
Pit entry decoder	192.168.1.12	Opens a pit stop
Pit exit decoder	192.168.1.13	Closes a pit stop

Replace these addresses with addresses from your own LAN.

The three address types

Value	Example	Consumer
Decoder IP	192.168.1.10	AMMC connects to the physical decoder
AMMC WebSocket	ws://192.168.1.100:9000	Browser connects to AMMC on the backend host
Backend URL	http://192.168.1.100:8081	Browser uses the web UI, API, and persistence

127.0.0.1 always means the current machine. Use ws://127.0.0.1:9000 only when the browser and backend run on the same computer. A remote laptop must use the backend LAN address.

Data path

car transponder -> physical loop -> physical decoder with its own IP
                -> AMMC process on backend -> unique backend WebSocket port
                -> browser/RaceController -> active session, results, statistics

Complete example:

Main      192.168.1.10 -> backend AMMC :9000 -> main/start-finish
Split     192.168.1.11 -> backend AMMC :9001 -> intermediate timing
Pit entry 192.168.1.12 -> backend AMMC :9002 -> open stop
Pit exit  192.168.1.13 -> backend AMMC :9003 -> close stop

Operator laptop opens http://192.168.1.100:8081 and connects to
ws://192.168.1.100:9000 through ws://192.168.1.100:9003.

Supported layouts

Installation	Decoders	Enabled roles
Normal timing	1	Main
Timing with split	2	Main + Split
Timing with pit stops	3	Main + Pit entry + Pit exit
Full endurance	4	Main + Split + Pit entry + Pit exit

Pit timing always needs both entry and exit. One pit decoder cannot calculate stop duration.

Roles and ports

Role	Example decoder IP	AMMC port	Counts laps?	Stored data
Main start/finish	192.168.1.10	9000	Yes	Passing, lap, and lap time
Split	192.168.1.11	9001	No	Split since latest main crossing
Pit entry	192.168.1.12	9002	No	Entry time and active driver/car
Pit exit	192.168.1.13	9003	No	Exit time and completed stop duration

Each physical decoder needs a unique IP. Each enabled AMMC process needs a unique WebSocket port.

Recommended Managed AMMC setup

AMMC runs on the computer started with npm start or npm.cmd start, not on a remote browser laptop.

1. Start the backend and open Settings.
2. From remote devices use backend URL http://192.168.1.100:8081.
3. Enable Managed AMMC.
4. Configure Main decoder host 192.168.1.10, port 9000.
5. If present, enable Split and configure host 192.168.1.11, port 9001.
6. If both pit decoders are present, enable Pit and configure entry .12/9002 and exit .13/9003.
7. Save AMMC and click Start AMMC.
8. Verify every enabled process reports Running without an error.
9. Click Use server WS URL.
10. Open Timing, click Connect decoder, and verify every enabled role is Connected.

Client WebSocket URLs for this example are:

Main      ws://192.168.1.100:9000
Split     ws://192.168.1.100:9001
Pit entry ws://192.168.1.100:9002
Pit exit  ws://192.168.1.100:9003

Do not put the physical decoder IP in the browser WebSocket URL. The WebSocket server is AMMC on the backend host.

Manual AMMC

Run one process per enabled role:

ammc-amb.exe -w 9000 192.168.1.10
ammc-amb.exe -w 9001 192.168.1.11
ammc-amb.exe -w 9002 192.168.1.12
ammc-amb.exe -w 9003 192.168.1.13

Syntax: ammc-amb -w <backend WebSocket port> <physical decoder IP>.

Disable Managed AMMC when starting these processes manually, otherwise two processes may compete for the same port.

Firewall

Open ports on the backend host, not the operator laptop.

Linux/UFW:

sudo ufw allow 8081/tcp
sudo ufw allow 9000:9003/tcp

Windows, from an elevated PowerShell:

Start-Process powershell -Verb RunAs -ArgumentList '-ExecutionPolicy Bypass -File .\windows\setup.ps1 -OpenFirewall -StartServer'

This opens TCP 8081 and 9000-9003. Use these ports only on a trusted LAN. Never expose the admin UI, API, or AMMC ports directly to the internet.

Verification order

1. Ping every physical decoder from the backend host.
2. Verify backend status with npm run status or npm.cmd run status.
3. Start Managed AMMC and inspect its log.
4. Connect decoder roles in Timing.
5. Cross Main: lap count must increase.
6. Cross Split: split changes but lap count does not.
7. Cross Pit entry: competitor becomes IN PIT.
8. Cross Pit exit: one timed pit stop is created.

Where the data appears

• Timing: live leaderboard, split, and pit log.
• Overlay: latest split and active pit state.
• Race Setup -> Manage -> Live / results: analysis per heat.
• Result/PDF exports: split/pit summary and complete pit log.
• Training -> More statistics: personal profile statistics for the selected class.
• Personal mobile profile: sanitized aggregates only; no transponder or raw pit log.

Troubleshooting

Symptom	Likely cause	Check
Decoder offline	Main WebSocket unavailable	AMMC main, port 9000, firewall
AMMC starts then exits	Decoder IP, binary, or library error	AMMC log and ping from backend
Remote laptop opens UI but receives no timing	URL uses 127.0.0.1	Use ws://<backend-IP>:9000
Main works but Split does not	Split disabled or port blocked	Decoder .11, port 9001, Timing status
Pit entry works but no stop closes	Pit exit missing/wrong role	Decoder .13, port 9003, separate loop
Split crossing increments laps	Feed assigned to wrong role	Use separate IP/port for Main and Split
EADDRINUSE	Duplicate AMMC port/process	Stop manual AMMC or assign unique ports

Invariants

• Only Main may count laps.
• Split and pit records must never be stored as normal lap passings.
• Pit entry and exit are separate roles.
• A stop remains attributed to the driver/car captured at pit entry during an endurance driver change.
• Driver statistics remain separated by class.