Skip to content

Pin Configuration (RaceLink WLED node)

Runtime configuration of the radio and ePaper pins on a flashed RaceLink WLED node. Build profiles still ship a per-target default set of pins so first boot picks the right wiring automatically; this page is for operators who need to override those defaults — typically on a custom or rewired board.

Audience. Operators of flashed RaceLink WLED nodes who already have the firmware running and want to relocate pins via the WLED settings UI instead of reflashing. For build-from-source instructions see README.md. For first-time pairing and basic operation see operator-setup.md.

When you need this page

The compile-time defaults baked into each shipping build profile match the reference hardware they target. You should only change pins if:

  • you built or modified a board with non-standard wiring,
  • you swapped a module variant whose pin breakout differs,
  • a pin conflicts with another WLED feature (e.g. an LED bus you configured later) and the radio or ePaper stops working.

If your hardware matches one of the supported reference boards and the firmware was flashed with the matching build profile, leave this page alone — the defaults are correct.

Where the settings live

Open the WLED Web UI → Config → Usermod Settings → RaceLink. Two sub-objects expose the pins:

  • pins — the radio control pins (always present).
  • epaper_pins — the ePaper bus and control pins (only present on builds compiled with -D RACELINK_EPAPER).

Each pin is a numeric input expecting a GPIO number. Set -1 if the pin is not wired (only meaningful for MISO, which most e-paper panels do not expose).

After saving, the node reboots automatically to re-init SPI on the new pins. The reboot only fires when at least one pin actually changes; saving the settings unchanged does not reboot.

Default pin assignments per supported build profile

The values below are the defaults compiled into each shipping profile. They become the starting point in the UI on first boot or after a factory reset.

Radio control pins (pins)

Pin HT-CT62 (v1_c3_ct62) Node v3 S2 (v3_s2_llcc68) Node v3 S2 + ePaper (v3_s2_llcc68_epaper) Node v4 S3 (v4_s3_llcc68) Heltec Wireless Paper (v6_s3_heltec_wpaper)
SCK 10 6 6 6 9
MISO 6 5 5 5 11
MOSI 7 4 4 4 10
NSS 8 3 3 3 8
DIO1 3 8 8 8 14
BUSY 4 9 9 9 13
RST 5 7 7 7 12

The fallback defaults compiled into racelink_wled.h match HT-CT62 (ESP32-C3 + SX1262) wiring — the v1_c3_ct62 column above. Every other profile overrides them via -D RACELINK_PIN_*=... in its platformio_override.ini. Check the relevant build profile in build_profiles/ for the authoritative numbers if you suspect a mismatch.

RaceLink_Node_v5_s3_eth has no radio; its W5500 pins live in eth_pins — see ../RaceLink_Host/ethernet-networks.md.

ePaper bus and control pins (epaper_pins)

Only present when the firmware was built with -D RACELINK_EPAPER — the v3_s2_llcc68_epaper and v6_s3_heltec_wpaper profiles.

Pin Node v3 S2 + ePaper (v3_s2_llcc68_epaper) Heltec Wireless Paper (v6_s3_heltec_wpaper)
SCK 13 3
MISO -1 (unused) -1 (unused)
MOSI 12 2
CS 14 4
DC 15 5
RST 16 6
BUSY 17 7

The v6 additionally gates the panel's power rail on VEXT = GPIO 45, active LOW; the v3 panel is always powered. The panel driver class is compile-time (GDEY037T03 by default, RACELINK_EPAPER_PANEL_E0213A367 on the v6, _FC1 for the other panel Heltec ships) and is not runtime-configurable.

The ePaper SPI bus is dedicated (HSPI on supported MCUs), separate from the radio bus, so SCK/MOSI/CS may freely overlap with the radio pins on different physical wires.

Reboot behavior

  • Changing any pin in either group triggers a reboot.
  • The first-boot deserialize that loads cfg.json does not trigger a reboot (it only reads the persisted values into the runtime members; nothing has changed).
  • The reboot is the standard WLED doReboot path — the same one used by the Settings → Reboot button. Allow ~5–10 seconds for the node to come back up; existing pairings are kept (master MAC stays persisted if MAC filter persist is on).

PinManager conflict troubleshooting

WLED uses an internal PinManager to prevent two subsystems from fighting over the same GPIO. If you assign a pin that is already claimed by another feature — most commonly the LED data bus — radioInit() (or epaperInit()) refuses to allocate and the subsystem fails to start.

Symptoms:

  • Info panel → "RaceLink Init" reads FAIL with a non-zero init code, and no on-air RaceLink traffic happens.
  • The serial log carries: [RaceLink] PinManager allocation failed (LED bus conflict?)
  • For ePaper: [RaceLink] ePaper PinManager allocation failed — display disabled — the radio still works, but the panel stays blank.

Resolution:

  1. Open Config → LED Preferences and check which GPIOs your LED bus(es) use.
  2. Open Config → Usermod Settings → RaceLink → pins (or epaper_pins).
  3. Move the conflicting pin to a free GPIO. Save → reboot.

Other common conflicts: button pin, IR pin, DMX pin. The Settings → Time & Macros page typically lists these. Free GPIOs depend on the SoC variant — see your board's datasheet for the output-capable pin set.