Live_RC/docs/decoder-setup.md

Decoder, IP, and AMMC configuration

This guide explains how physical MyLaps/AMB decoders connect to RC RaceCore. It uses this example network:

Device	Example address	Purpose
RC RaceCore/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/RC RaceCore -> 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.

On x86-64 Linux, all bundled programs in AMMC/linux_x86-64 require GLIBC 2.39 or newer. Check with ldd --version or npm run verify. RC RaceCore itself may run on an older host, but these bundled AMMC programs will not.

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.

Fake decoder with AMMC Simulator

ammc-sim emulates a physical decoder. It does not replace the AMMC WebSocket converter: run the simulator first, then point ammc-amb at the simulator host. Keep this setup off the live decoder network during an official race.

Linux example with four simulated drivers and a passing every 15 to 22 seconds:

./AMMC/linux_x86-64/ammc-sim \
  --transponder 1111111,2222222,3333333,4444444 \
  --passing-delay 15000-22000 \
  --my_ip 192.168.1.100 \
  --skip_telemetry_upload \
  AMB

./AMMC/linux_x86-64/ammc-amb -w 9000 192.168.1.100

Windows uses the same arguments with ammc-sim.exe and ammc-amb.exe. Replace 192.168.1.100 with the computer running the simulator. RC RaceCore still connects to ws://<AMMC-host>:9000. Use transponder numbers registered in RC RaceCore, or use Open Practice to display unknown numbers directly.

Useful simulator options:

Option	Purpose
--transponder 123,456	IDs emitted by the fake decoder
--passing-delay 15000-22000	Random delay between passings in milliseconds
--passing-numbers 1-500	Stop after the configured passing-number range
--startup_delay_secs 5	Wait before sending passings
--my_ip <address>	Address returned during decoder auto-discovery

Run ammc-sim --help for the options supported by the bundled version. The simulator is a test input only; all lap validation, stint handling, leaderboard updates, and persistence continue through the normal RaceCore event pipeline.

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
GLIBC_2.39 not found	Bundled Linux AMMC is newer than the host GLIBC	Use GLIBC 2.39+ or a compatible AMMC build; never replace system GLIBC manually
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.