Skip to content

RaceLink Documentation

Consolidated public documentation of the RaceLink ecosystem — a wireless LED-control system for drone racing and similar live events.

The project is split across four repositories. This documentation set gathers the Markdown documents from all four projects in one place, organised for public consumption.

Source of truth. Files in this directory are English copies derived from the source repositories. Originals remain canonical; see SOURCES.md for the per-file provenance. When a source repository changes, this consolidated copy may lag.

System overview

RaceLink_Host  <--USB-->  RaceLink_Gateway  <--LoRa-->  RaceLink nodes
                                                        ├─ RaceLink_WLED
                                                        ├─ Startblocks
                                                        └─ Custom nodes

(optional: RaceLink_RH_Plugin → embeds RaceLink_Host into RotorHazard)
Component Role Repository
RaceLink_Host Python host: runtime, WebUI, services, standalone Flask PSi86/RaceLink_Host
RaceLink_Gateway ESP32-S3 firmware: USB ↔ LoRa bridge PSi86/RaceLink_Gateway
RaceLink_WLED WLED usermod + build profiles for RaceLink nodes PSi86/RaceLink_WLED
RaceLink_RH_Plugin RotorHazard adapter; embeds RaceLink_Host as a plugin PSi86/RaceLink_RH-plugin

Repository layout

docs/
├── README.md                    (this document)
├── SOURCES.md                   (file-by-file provenance)
├── GLOSSARY.md                  (canonical term reference)
├── LICENSES.md                  (per-component licence list)
├── VERSIONING.md                (cross-component compatibility)
├── CONTRIBUTING.md              (PR rules, smoke tests, conventions)
├── CHANGELOG.md                 (release timeline)
├── TROUBLESHOOTING.md           (operator-side index)
├── HARVEST.md                   (what was mined from plans/)
├── AUDIT_RESPONSE.md            (how each audit finding was addressed)
│
├── host/                        RaceLink_Host (Python)
│   ├── README.md
│   ├── ARCHITECTURE.md
│   └── docs/
│       ├── OPERATOR_GUIDE.md
│       ├── DEVELOPER_GUIDE.md
│       ├── PROTOCOL.md
│       ├── UI_CONVENTIONS.md
│       └── standalone.md
│
├── gateway/                     RaceLink_Gateway (firmware)
│   ├── README.md                (build / development)
│   └── OPERATOR.md              (operator setup)
│
├── wled/                        RaceLink_WLED (usermod)
│   ├── README.md                (build profiles)
│   ├── OPERATOR.md              (operator setup)
│   └── docs/
│       └── effects-deterministic.md
│
├── rh-plugin/                   RaceLink_RH_Plugin
│   ├── README.md
│   ├── OPERATOR.md              (operator setup inside RotorHazard)
│   └── docs/
│       ├── release-playbook.md
│       └── manifest-dependency-format.md
│
├── reference/                   Cross-component reference
│   ├── SCENE_FORMAT.md
│   ├── SSE_CHANNELS.md
│   └── WEB_API.md
│
└── maintainer/                  Maintainer-only material
    └── adr/
        ├── README.md
        └── 0001-rh-plugin-manifest-dependency.md

The host/docs/repo_split_map.md file from the source has been folded into host/ARCHITECTURE.md (its content is small and reads as a historical note alongside the architecture description). The plans/ archive in the source is not mirrored here — it is an internal engineering ledger; relevant content has been harvested into the appropriate documents (see HARVEST.md).

Recommended entry points by audience

Operators (setting up an event)

  1. host/docs/standalone.md — install and run the host on Windows / Linux.
  2. host/docs/OPERATOR_GUIDE.md — end-to-end workflow, safety rules, offset-mode operator view, troubleshooting.
  3. gateway/OPERATOR.md — connect the USB gateway, identify it on the host, OLED indicators.
  4. wled/OPERATOR.md — pair a node, factory reset, default Wi-Fi AP and OTA password.
  5. wled/README.md — pick the right build profile for your hardware.
  6. rh-plugin/OPERATOR.md — operator view inside RotorHazard if you run the plugin.
  7. TROUBLESHOOTING.md — single index of common problems and where to find them.

Contributors (code changes or extensions)

  1. host/ARCHITECTURE.md — package layout, threading model, locking rules, UI scope matrix.
  2. host/docs/DEVELOPER_GUIDE.md — checklists for "I want to add X": new scene action, new opcode, new service, WLED metadata regeneration.
  3. host/docs/PROTOCOL.md — wire-format reference (USB framing, Header7, opcodes, body layouts, gateway state machine).
  4. host/docs/UI_CONVENTIONS.md — button vocabulary, toast / confirm-dialog conventions.
  5. CONTRIBUTING.md — PR rules, smoke-test commands, exception-hygiene convention, the bool send contract.
  6. VERSIONING.md — version compatibility across Host / Gateway / WLED / RH plugin.

Firmware developers (gateway / WLED nodes)

  1. gateway/README.md — PlatformIO setup, hardware targets, build flags, USB framing.
  2. wled/README.md — build profiles per hardware variant, release workflow.
  3. wled/docs/effects-deterministic.md — which WLED effects render identically when only strip.timebase is synced (prerequisite for offset mode + ARM-on-SYNC).
  4. host/docs/PROTOCOL.md — the wire format that the firmware must respect.

Plugin maintainers (RotorHazard integration)

  1. rh-plugin/README.md — scope, online vs. offline installation, version mapping between plugin and host.
  2. rh-plugin/docs/release-playbook.md — step-by-step maintainer release.
  3. rh-plugin/docs/manifest-dependency-format.md — why the git+https:// dependency format is required by RHFest.

A note on cross-references

The source documents contain links that originally pointed into the respective source repository's source code (racelink/services/foo.py, racelink_proto.h, etc.). Those links cannot resolve in this documentation-only consolidation. For source-code references, see the matching source repository — the canonical paths are recorded in SOURCES.md.

Markdown-to-Markdown links within a sub-project's directory still work, because each repository's original folder layout is preserved under its sub-directory.

Licence

Each source repository carries its own licence. See LICENSES.md for the per-component table. This documentation set does not alter the licensing of the underlying material.