Skip to content

Supported hardware

Every board RaceLink ships a firmware build for — what it is, who makes it, which GPIO does what, and the few properties you cannot change after you have bought it.

Audience. Anyone choosing, buying or wiring hardware. This page names devices and pins; it does not cover putting firmware on them (see flashing.md), building from source (see RaceLink_Gateway/README.md and RaceLink_WLED/README.md), or re-assigning pins on a device that already runs (see RaceLink_WLED/pin-config.md).

A RaceLink system is one or more gateways plus any number of nodes. The gateway is a USB dongle on the host machine; the nodes are what drives the LEDs out on the track.

Gateways

Both supported gateways are ESP32-S3 + SX1262 boards from Heltec and run the same firmware with the same pin map. They differ only in the OLED panel — and in how they reach the host over USB.

Board SoC Flash Radio OLED USB Build env
Heltec Wireless Stick V3 ESP32-S3FN8 8 MB SX1262 0.49″ 64×32 CP2102 bridge WirelessStickV3-ESP32S3
Heltec WiFi LoRa 32 V4 ESP32-S3R2 / R8 16 MB (+ PSRAM) SX1262 0.96″ 128×64 native USB-Serial/JTAG HeltecWiFiLoRa32V4-ESP32S3

Both report DEV_TYPE=1 (RaceLink_Gateway_v4) to the host — the host does not distinguish them. Flashing the wrong one of the two gives a working gateway with a garbled display, not a brick.

Gateway pin map

Identical on both boards; fixed at compile time in platformio.ini (the gateway has no runtime pin configuration).

GPIO Signal Function
8 RACELINK_CS SX1262 chip select (SPI)
9 RACELINK_SCK SPI clock
10 RACELINK_MOSI SPI data, MCU → modem
11 RACELINK_MISO SPI data, modem → MCU
12 RACELINK_RST SX1262 reset
13 RACELINK_BUSY SX1262 busy handshake (SX126x family)
14 RACELINK_DIO1 SX1262 interrupt — TX-done / RX-done / timeout
17 OLED_SDA SSD1306 I²C data
18 OLED_SCL SSD1306 I²C clock
21 OLED_RST SSD1306 reset
36 PIN_VEXT Peripheral power rail — driven LOW = on
0 BUTTON_PIN User button (INPUT_PULLUP, falling-edge IRQ) — long press ≥ 1 s toggles the OLED debug view, short press forces a status redraw

A gateway needs at least 8 MB of flash

The gateway pins an 8 MB partition table, which a 4 MB ESP32-S3 module cannot hold. Both boards above qualify; a random 4 MB S3 dev board does not. See flashing.md.

Why the V4 needs no USB driver

The V4 carries no CP2102 — its only USB connection is the ESP32-S3's own USB-Serial/JTAG peripheral, so it builds with -D ARDUINO_USB_CDC_ON_BOOT=1 and appears as a plain USB Serial Device. The V3 boards do have a CP2102 and deliberately do not set that flag. Driver table: flashing.md.

Nodes

Node firmware is the RaceLink_WLED usermod compiled into upstream WLED, one build profile per hardware variant.

Build env Hardware SoC Transport DEV_TYPE Display
RaceLink_Node_v1_c3_ct62 Heltec HT-CT62 module ESP32-C3FN4 (4 MB) SX1262 10 —
RaceLink_Node_v3_s2_llcc68 self-wired board ESP32-S2 LLCC68 11 —
RaceLink_Node_v3_s2_llcc68_epaper self-wired board + e-paper ESP32-S2 LLCC68 50 3.7″ 240×416 (GDEY037T03)
RaceLink_Node_v4_s3_llcc68 self-wired board ESP32-S3 LLCC68 12 —
RaceLink_Node_v5_s3_eth Waveshare ESP32-S3-ETH ESP32-S3 Wiznet W5500 Ethernet — no radio 13 —
RaceLink_Node_v6_s3_heltec_wpaper Heltec Wireless Paper ESP32-S3FN8 (8 MB) SX1262 51 2.13″ 250×122 e-paper

DEV_TYPE 50 and 51 are Startblocks — the two device types that carry pilot-slot config and render a per-slot e-paper layout. The rest are plain light nodes.

The v3 and v4 profiles target boards you wire yourself: they name a stock PlatformIO board definition (sparkfun_esp32s2_thing_plus, esp32-s3-devkitc-1) only to pick the right SoC and flash settings — the radio is a module you connect to the pins below. The v1, v5 and v6 profiles target the off-the-shelf products linked in the table.

Radio pins (SX1262 / LLCC68)

Same seven signals on every radio profile; only the GPIO numbers differ. RaceLink_Node_v5_s3_eth has no radio and is absent from this table.

Signal Function v1 (HT-CT62) v3 / v3-epaper / v4 v6 (Wireless Paper)
SCK SPI clock 10 6 9
MISO SPI data, modem → MCU 6 5 11
MOSI SPI data, MCU → modem 7 4 10
NSS Chip select 8 3 8
DIO1 Modem interrupt (TX/RX done, timeout) 3 8 14
BUSY Modem busy handshake 4 9 13
RST Modem reset 5 7 12

These are defaults, not hard wiring

On a flashed node the radio, e-paper and Ethernet pins are all runtime-configurable under Config → Usermod Settings → RaceLink. The build flags above only seed first boot. What stays compile-time is the chip family (-D RACELINK_SX1262 vs -D RACELINK_LLCC68) — see RaceLink_WLED/radio-modules.md.

LED, button and battery pins

Signal Function v1 v3 / v3-epaper / v4 v5 (ETH) v6 (W-Paper)
DATA_PINS[0] LED bus 1 data out 2 2 2 47
DATA_PINS[1] LED bus 2 data out — (1 bus only) 11 4 48
BTNPIN Mode / factory-reset button 9 0 0 0
battery ADC Battery voltage sense 0 1 1 1

Every profile defaults to WS2812 RGB, GRB order, 100 pixels per bus. The battery divider multiplier is 11.2 everywhere except v1, which uses the ESP32 default.

The button does not do what the WLED build flags suggest

Every profile compiles in WLED's stock WLED_LONG_AP=5000 and WLED_LONG_FACTORY_RESET=15000, but neither fires. The usermod's handleButton() returns true for this button, which makes upstream button.cpp skip its own press-duration logic entirely, and the usermod runs its own gesture state machine instead: the Wi-Fi AP is a three-click, press-and-hold fades brightness, and a five-click toggles Headless Mode. The full gesture table is in RaceLink_WLED/operator-setup.md.

The v6 LED pins are placeholders

GPIO 47/48 are free, output-capable S3 pins picked so they collide with nothing — the Wireless Paper has no LED connector. Set them to match your actual wiring, and keep clear of the e-paper (2–7), LoRa (8–14) and Vext (45) pins.

E-paper pins (Startblocks)

Only present on builds compiled with -D RACELINK_EPAPER. The e-paper SPI bus is separate from the radio bus, so pin numbers may repeat across the two tables — they are different physical wires.

Signal Function v3-epaper v6 (Wireless Paper)
SCK SPI clock 13 3
MOSI SPI data, MCU → panel 12 2
MISO Unused on both panels -1 -1
CS Chip select 14 4
DC Data / command select 15 5
RST Panel reset 16 6
BUSY Panel busy (refresh in progress) 17 7
VEXT Panel power rail — (always powered) 45, LOW = on

The panel driver class is compile-time, because the controller ICs are not compatible: GDEY037T03 (UC8253) is the default, and the Wireless Paper selects E0213A367 (SSD1682) — with RACELINK_EPAPER_PANEL_FC1 (Fitipower JD79656) as the alternative, since Heltec ships that board with two different 2.13″ panels. If your panel stays blank on a v6 node, that switch is the first thing to check.

Ethernet pins (v5, W5500)

Signal Function GPIO
SCLK SPI clock 13
MOSI SPI data, MCU → W5500 11
MISO SPI data, W5500 → MCU 12
CS Chip select 14
RST W5500 reset 9
INT W5500 interrupt 10

The node listens on UDP port 5078 and answers the host on 5079, takes DHCP by default with a build-time static-IP fallback, and needs no gateway — it talks to the host directly over the LAN. Full picture: RaceLink_Host/ethernet-networks.md.

Radio defaults

Every LoRa profile — gateway and node — compiles in the same EU868 starting point:

Parameter Value
Frequency 867.7 MHz
Bandwidth 125 kHz
Spreading factor 7
Coding rate ⅘
Sync word 0x12
Preamble 8 symbols
TX power 14 dBm

The frequency is a default, not a limit: the firmware accepts 863–928 MHz at runtime, so operators outside the EU do not need to build from source. Set it at flash time or from the host — see reference/channels.md.

What you cannot change in software

Three properties are decided when you buy the board. Get them wrong and no amount of configuration helps.

  • The frequency band. Heltec sells these boards as separate 433 / 470–510 / 863–870 / 902–928 MHz hardware. The band cannot be detected over USB and cannot be changed in firmware — match the board to your region when you order.
  • Flash size. A gateway needs ≥ 8 MB. Nodes fit in 4 MB.
  • The SoC family. An ESP32-S3 image does not boot on an ESP32-C3. Match the build env to the board.

One more, decided at build time rather than purchase: the radio chip family (SX1262 vs LLCC68) and, on Startblocks, the e-paper panel class.