Skip to content

RaceLink Standalone Guide

This guide explains how to install and run racelink-host in standalone mode on Windows and Linux.

Standalone mode runs the RaceLink host runtime and the shared RaceLink WebUI without RotorHazard. It is intended for gateway-backed operation, so a connected RaceLink Gateway is expected for normal use.

Requirements

  • Python 3.10 or newer
  • A terminal or shell
  • A RaceLink Gateway connected by USB for normal operation
  • Network access to install Python packages

The packaged standalone entrypoint is:

racelink-standalone

Default standalone URL:

http://127.0.0.1:5077/racelink

Windows installation and usage

Create and activate a virtual environment:

py -3 -m venv .venv
.venv\Scripts\Activate.ps1

Install RaceLink Host:

python -m pip install --upgrade pip
python -m pip install racelink-host

Start standalone mode:

racelink-standalone

Open the UI in a browser:

http://127.0.0.1:5077/racelink

Stop the server with Ctrl+C.

Windows notes:

  • The RaceLink Gateway usually appears as a COM port such as COM3 or COM4
  • If multiple serial devices are connected, confirm which COM port belongs to the gateway in Device Manager
  • If the UI loads but the gateway is not detected, check the configured port and the USB connection first

Linux installation and usage

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install RaceLink Host:

python -m pip install --upgrade pip
python -m pip install racelink-host

Start standalone mode:

racelink-standalone

Open the UI in a browser:

http://127.0.0.1:5077/racelink

Stop the server with Ctrl+C.

Linux notes:

  • The RaceLink Gateway usually appears as a serial device such as /dev/ttyUSB0 or /dev/ttyACM0
  • If RaceLink cannot open the gateway, check user permissions for serial devices
  • On some systems you may need to add the user to a group such as dialout
  • Wi-Fi helper features that depend on nmcli only work in environments where NetworkManager and nmcli are installed

Linux first-time setup for firmware updates

The OTA flow connects the host's WiFi directly to a WLED node's AP via nmcli dev wifi connect <SSID> password <PASS> and disconnects it afterwards. No pre-created NetworkManager profile is required — NM creates one persistent profile per SSID on first connect and reuses it on subsequent runs.

The nmcli command needs polkit authorisation. On a fresh Linux host, run the bundled setup helper once as root to grant the running user unattended access:

sudo apt install network-manager       # Debian/Ubuntu/Pi OS only
sudo $(which racelink-setup-nmcli)     # absolute path; see below
# restart the host (RotorHazard or racelink-standalone) so the running
# Python process re-establishes its polkit subject

racelink-setup-nmcli is shipped as a console script alongside racelink-standalone, so a pip install racelink-host puts it on the host's PATH. Use sudo $(which racelink-setup-nmcli) rather than the bare command — sudo's default secure_path strips the venv's bin/ directory, so sudo racelink-setup-nmcli fails with command not found on piwheel / venv installs (the typical RotorHazard plugin layout). The OTA failure dialog also surfaces the exact absolute command for the install you're running, so you can copy-paste it directly from the toast if which isn't on your PATH either.

The helper is idempotent: adds the user to the netdev (or wheel on Fedora/RHEL) group and installs a polkit rule at /etc/polkit-1/rules.d/49-racelink-nmcli.rules that authorises org.freedesktop.NetworkManager.* actions for that specific user. Verify with nmcli dev wifi list — if it lists nearby APs without prompting for a password, the host is ready.

If you've cloned the source repo instead of installing via pip, the equivalent bash variant lives at scripts/setup_nmcli_polkit.sh and writes the same polkit rule.

The Firmware Update dialog ships sensible defaults (SSID list WLED_RaceLink_AP, WLED-AP, password wled1234). Override per-OTA if your fleet uses a custom WLED AP password.

Configuration file

Standalone mode stores its local configuration in:

~/.racelink/standalone_config.json

On Windows this usually expands to something like:

C:\Users\<username>\.racelink\standalone_config.json

On Linux this usually expands to something like:

/home/<username>/.racelink/standalone_config.json

Example configuration:

{
  "host": "127.0.0.1",
  "port": 5077,
  "debug": false,
  "options": {
    "psi_comms_port": "COM3"
  }
}

Useful fields:

  • host: bind address for the standalone Flask server
  • port: TCP port for the standalone Flask server
  • debug: Flask debug mode
  • options: persisted RaceLink options used by the host runtime

To change the bind address or port, edit the config file before starting racelink-standalone.

Verifying that standalone mode works

After starting the server:

  1. Open http://127.0.0.1:5077/
  2. Confirm it redirects to /racelink
  3. Confirm the RaceLink WebUI loads successfully
  4. Watch the terminal output for gateway startup messages

Expected behavior:

  • Without a connected gateway, the UI can still load, but gateway communication will not be ready
  • With a connected gateway, standalone mode should report that the communicator is ready and the WebUI should be able to interact with RaceLink services

Manual validation checklist

  • Create a fresh virtual environment
  • Install racelink-host
  • Start racelink-standalone
  • Open the browser at /racelink
  • Confirm / redirects to /racelink
  • Confirm the shared RaceLink WebUI loads
  • Confirm the gateway is reported as unavailable when no gateway is connected
  • Confirm the gateway is detected when the correct serial port is configured and the hardware is connected